@indigoai-us/hq-cloud 6.11.12 → 6.11.13

package/src/bin/sync-runner.ts

@@ -106,36 +106,32 @@ import { collectAndSendTelemetry } from "../telemetry.js";
 import { collectAndSendSkillTelemetry } from "../skill-telemetry.js";
 import { reindexAfterSync } from "../qmd-reindex.js";
 import { pruneConflictIndex } from "../lib/conflict-index.js";
-import {
-  acquireOperationLock,
-  withOperationLock,
-  OperationLockedError,
-  OPERATION_LOCKED_EXIT,
-} from "../operation-lock.js";
-import { describeError } from "../lib/describe-error.js";
 import { getOrCreateMachineId } from "../lib/machine-id.js";
+import type { Clock, TreeChangeBatch } from "../watcher.js";
+import type { PushReceiver, SyncEngineFn } from "../sync/push-receiver.js";
 import {
-  TreeWatcher,
-  WatchPushDriver,
-  systemClock,
-  type Clock,
-  type TreeChangeBatch,
-} from "../watcher.js";
-import {
-  NoopPushReceiver,
-  type PushReceiver,
-  type SyncEngineFn,
-} from "../sync/push-receiver.js";
-import {
-  resolveEventSync,
-  startEventSync as defaultStartEventSync,
   type EventSyncHandles,
   type StartEventSyncOptions,
 } from "../sync/event-sync.js";
+import { migratePersonalVaultJournal } from "../journal.js";
+import { createRunnerEmitter } from "./sync-runner-events.js";
 import {
-  PERSONAL_VAULT_JOURNAL_SLUG,
-  migratePersonalVaultJournal,
-} from "../journal.js";
+  buildFanoutPlan,
+  emitFanoutPlan,
+  resolveMembershipsForRun,
+} from "./sync-runner-planning.js";
+import { executeCompanyFanout } from "./sync-runner-company.js";
+import { rollupAllComplete } from "./sync-runner-rollup.js";
+import { emitTelemetry } from "./sync-runner-telemetry.js";
+import {
+  runOneShotWithOperationLock,
+  runWatchLoop,
+} from "./sync-runner-watch-loop.js";
+export {
+  buildTargetedPullArgv,
+  buildTargetedPushArgv,
+  routeChangeToTarget,
+} from "./sync-runner-watch-routes.js";
 
 /**
  * Sync direction for a run.
@@ -894,14 +890,7 @@ export async function runRunner(
   // events. The menubar's `HQ_CLOUD_VERSION` pin gates which runner
   // they spawn, so old menubars stay on the previous runner version
   // even after this one is published.
-  const ERROR_TYPES: ReadonlySet<RunnerEvent["type"]> = new Set([
-    "error",
-    "auth-error",
-  ]);
-  const emit = (event: RunnerEvent): void => {
-    const stream = ERROR_TYPES.has(event.type) ? stderr : stdout;
-    stream.write(`${JSON.stringify(event)}\n`);
-  };
+  const emit = createRunnerEmitter({ stdout, stderr });
 
   // ---- argv -------------------------------------------------------------
   const parsed = parseArgs(argv);
@@ -993,36 +982,21 @@ export async function runRunner(
   // ---- resolve targets --------------------------------------------------
   let memberships: Pick<Membership, "companyUid">[];
   try {
-    if (parsed.personal) {
-      // Personal-vault-only mode: skip listMyMemberships entirely (and
-      // therefore the claim-dance). The fanout plan is built solely from
-      // the person-entity lookup below — no cloud-company targets, no
-      // /membership/me round-trip. setup-needed is deferred to the
-      // person-entity check (firing only when the personal entity is
-      // also absent, not when memberships are empty by design).
-      memberships = [];
-    } else if (parsed.companies) {
-      // Before giving up on memberships, run the claim-dance: new users signed
-      // in via the tray may have email-keyed invites waiting for them. Without
-      // this, an invited user would see "setup-needed" on every tray click.
-      if (claims) {
-        await runClaimDance(client, claims, stderr);
-      }
-
-      memberships = await listMembershipsWithRetry(client);
-      if (memberships.length === 0) {
-        // Truly empty — still a valid state (no memberships = nothing to
-        // sync). The tray will show a friendly "create your first company"
-        // CTA rather than an alarm banner.
-        emit({ type: "setup-needed" });
-        return 0;
-      }
-    } else {
-      // Single-company mode: fabricate a minimal membership so the fanout
-      // loop below treats it uniformly. We don't need to hit
-      // /membership/me — the caller already told us which company.
-      memberships = [{ companyUid: parsed.company! }];
+    const resolution = await resolveMembershipsForRun({
+      personal: parsed.personal,
+      companies: parsed.companies,
+      company: parsed.company,
+      client,
+      claims,
+      stderr,
+      runClaimDance,
+      listMemberships: listMembershipsWithRetry,
+    });
+    if (resolution.status === "setup-needed") {
+      emit({ type: "setup-needed" });
+      return 0;
     }
+    memberships = resolution.memberships;
   } catch (err) {
     if (err instanceof VaultAuthError) {
       emit({
@@ -1042,73 +1016,21 @@ export async function runRunner(
     return 1;
   }
 
-  // ---- resolve slugs for the fanout plan --------------------------------
-  // The menubar wants "Syncing indigo" in its UI, not the raw cmp_* ULID.
-  // If the entity fetch fails for some row (entity deleted, scoping issue),
-  // degrade to using the UID as the slug rather than aborting the run.
-  const plan: Array<{
-    uid: string;
-    slug: string;
-    name?: string;
-    bucketName?: string;
-    personalMode?: boolean;
-    journalSlug?: string;
-  }> = [];
-  for (const m of memberships) {
-    let slug = m.companyUid;
-    let name: string | undefined;
-    try {
-      const info = await client.entity.get(m.companyUid);
-      slug = info.slug || m.companyUid;
-      name = info.name;
-    } catch {
-      // Best-effort — keep UID as the display identifier.
-    }
-    plan.push({ uid: m.companyUid, slug, ...(name ? { name } : {}) });
-  }
-
-  if (
-    (parsed.companies || parsed.personal) &&
-    !resolveSkipPersonal(parsed.skipPersonal)
-  ) {
-    // Personal-target fanout slot. Skipped entirely when --skip-personal
-    // (or HQ_SYNC_SKIP_PERSONAL=1) is set — see resolveSkipPersonal doc for
-    // the rationale (menubar opt-out for users who only want company sync).
-    // When skipped, the fanout-plan event below carries only company
-    // memberships and no "personal" slug; downstream consumers (menubar
-    // workspaces row, status surfaces) should already tolerate that
-    // shape since pre-5.25 fanout often had it (a user with no person
-    // entity yet, or before the canonical-person-entity machinery landed).
-    //
-    // `--personal` mode reaches this block with an empty `plan` and
-    // empty `memberships`; only the personal target gets added below.
-    const persons = await client.entity.listByType("person");
-    const pick = pickCanonicalPersonEntity(persons);
-    if (pick?.bucketName) {
-      plan.push({
-        slug: "personal",
-        uid: pick.uid,
-        bucketName: pick.bucketName,
-        personalMode: true,
-        // Reserved sentinel slug — decoupled from the `companies/personal`
-        // company slug to avoid sharing `sync-journal.personal.json`. The
-        // display `slug` stays "personal" (menubar UI); only the journal
-        // shard changes. See PERSONAL_VAULT_JOURNAL_SLUG for the full
-        // root-cause writeup.
-        journalSlug: PERSONAL_VAULT_JOURNAL_SLUG,
-      });
-    } else if (parsed.personal) {
-      // --personal mode with no canonical personal entity → setup-needed.
-      // (In --companies mode this state is silent — companies still sync
-      // and the missing personal target just shows an empty workspaces row.
-      // In --personal mode it's the ONLY signal, so it gets surfaced as
-      // setup-needed with the same shape as the empty-memberships case.)
-      emit({ type: "setup-needed" });
-      return 0;
-    }
+  const targetPlan = await buildFanoutPlan({
+    memberships,
+    companies: parsed.companies,
+    personal: parsed.personal,
+    skipPersonal: parsed.skipPersonal,
+    client,
+    resolveSkipPersonal,
+  });
+  if (targetPlan.status === "setup-needed") {
+    emit({ type: "setup-needed" });
+    return 0;
   }
+  const plan = targetPlan.plan;
 
-  emit({ type: "fanout-plan", companies: plan });
+  emitFanoutPlan(emit, plan);
 
   // One-time seed of the reserved personal-vault journal from the legacy
   // "personal" journal, so switching the vault slot off the colliding slug
@@ -1120,552 +1042,46 @@ export async function runRunner(
   // ---- fanout -----------------------------------------------------------
   const syncFn = deps.sync ?? defaultSync;
   const shareFn = deps.share ?? defaultShare;
-  const doPush = parsed.direction === "push" || parsed.direction === "both";
-  const doPull = parsed.direction === "pull" || parsed.direction === "both";
-  const errors: Array<{ company: string; message: string }> = [];
-  const allConflicts: Array<{ company: string; path: string; direction: "pull" | "push" }> = [];
-
-  // Per-company state, keyed by the company label (slug or UID-fallback) so
-  // both `progress` (which streams) and `complete`/throw (which lands once)
-  // can update the same row. The rollup at the bottom of the function walks
-  // every entry — this is the source of truth that closes the bug where an
-  // aborted company's partial counts were dropped from `all-complete`.
-  //
-  // We seed `direction` from the parsed flag so we know whether a `progress`
-  // event without a clear phase should bump downloaded or uploaded counters.
-  // For `direction: "both"` runs we lean on the path of the in-flight phase
-  // — push runs first and sets `phaseRef.current = "push"` while shareFn runs,
-  // pull sets it to "pull". The closure shared by tagAndEmit reads `.current`
-  // at event time, so progress events route to the right column.
-  type CompanyStatus = "complete" | "aborted" | "errored";
-  interface CompanyState {
-    company: string;
-    status: CompanyStatus;
-    filesDownloaded: number;
-    bytesDownloaded: number;
-    filesUploaded: number;
-    bytesUploaded: number;
-  }
-  const stateByCompany = new Map<string, CompanyState>();
-
-  for (const target of plan) {
-    const companyLabel = target.slug;
-    const state: CompanyState = {
-      company: companyLabel,
-      // Default to "errored" so a throw before any complete-or-clean-abort
-      // path (the original bug) leaves the entry flagged as not-clean. The
-      // success/clean-abort paths overwrite this before the loop body exits.
-      status: "errored",
-      filesDownloaded: 0,
-      bytesDownloaded: 0,
-      filesUploaded: 0,
-      bytesUploaded: 0,
-    };
-    stateByCompany.set(companyLabel, state);
-
-    // Which phase is currently emitting `progress` events. Mutable closure so
-    // tagAndEmit (defined once below) reads the latest value when each event
-    // fires. "pull" is the default for back-compat with pull-only runs.
-    let activePhase: "pull" | "push" = doPush && !doPull ? "push" : "pull";
-
-    // Per-company event tagger — shared by push and pull phases so progress
-    // rows land on the right company regardless of which phase emitted them.
-    // Also updates `state` for `progress` events so the rollup has accurate
-    // partial counts even if the sync function throws before returning.
-    let companyHadTransferError = false;
-    const tagAndEmit = (event: SyncProgressEvent): void => {
-      if (event.type === "plan") {
-        emit({
-          type: "plan",
-          company: companyLabel,
-          filesToDownload: event.filesToDownload,
-          bytesToDownload: event.bytesToDownload,
-          filesToUpload: event.filesToUpload,
-          bytesToUpload: event.bytesToUpload,
-          filesToSkip: event.filesToSkip,
-          filesToConflict: event.filesToConflict,
-          filesToDelete: event.filesToDelete,
-        });
-      } else if (event.type === "progress") {
-        if (activePhase === "push") {
-          state.filesUploaded += 1;
-          state.bytesUploaded += event.bytes;
-        } else {
-          state.filesDownloaded += 1;
-          state.bytesDownloaded += event.bytes;
-        }
-        emit({
-          type: "progress",
-          company: companyLabel,
-          path: event.path,
-          bytes: event.bytes,
-          // Stamp the transfer direction from the in-flight phase so the
-          // menubar can label each file uploaded vs downloaded. The inner
-          // share()/sync() emitters don't know the phase — only this tagger,
-          // which mirrors the up/down counter bump above.
-          direction: activePhase === "push" ? "up" : "down",
-          ...(event.message ? { message: event.message } : {}),
-          ...(event.deleted ? { deleted: event.deleted } : {}),
-        });
-      } else if (event.type === "conflict") {
-        emit({
-          type: "conflict",
-          company: companyLabel,
-          path: event.path,
-          direction: event.direction,
-          resolution: event.resolution,
-        });
-      } else if (event.type === "error") {
-        companyHadTransferError = true;
-        errors.push({
-          company: companyLabel,
-          message: event.path ? `${event.path}: ${event.message}` : event.message,
-        });
-        emit({
-          type: "error",
-          company: companyLabel,
-          path: event.path,
-          message: event.message,
-        });
-      } else if (event.type === "new-files") {
-        emit({
-          type: "new-files",
-          company: companyLabel,
-          files: event.files,
-        });
-      } else if (event.type === "scope-excluded") {
-        // Push-side ACL scope exclusions — surface the named paths tagged to
-        // this company so the menubar/CLI can show "N skipped, outside your
-        // access" instead of the file silently never uploading.
-        emit({
-          type: "scope-excluded",
-          company: companyLabel,
-          count: event.count,
-          samplePaths: event.samplePaths,
-        });
-      }
-    };
-
-    try {
-      let pushResult: ShareResult = {
-        filesUploaded: 0,
-        bytesUploaded: 0,
-        filesSkipped: 0,
-        filesDeleted: 0,
-        filesTombstoned: 0,
-        filesRefusedStale: 0,
-        filesRefusedStalePaths: [],
-        filesSuppressedByTombstone: 0,
-        filesExcludedByPolicy: 0,
-        filesExcludedByScope: 0,
-        conflictPaths: [],
-        aborted: false,
-      };
-      let pullResult: SyncResult = {
-        filesDownloaded: 0,
-        bytesDownloaded: 0,
-        filesSkipped: 0,
-        conflicts: 0,
-        conflictPaths: [],
-        aborted: false,
-        newFiles: [],
-        newFilesCount: 0,
-        filesExcludedByPolicy: 0,
-        filesTombstoned: 0,
-        filesOutOfScope: 0,
-        scopeOrphansRemoved: 0,
-        scopeOrphansBlocked: 0,
-      };
-
-      // Push first so a subsequent pull doesn't overwrite files we were about
-      // to broadcast. Company targets walk `companies/{slug}/`; the personal
-      // target walks every top-level entry under hqRoot minus the exclusion
-      // list (see PERSONAL_VAULT_EXCLUDED_TOP_LEVEL). `skipUnchanged: true`
-      // keeps both cases efficient on re-runs.
-      // Shared between push and pull for the personal slot. Hoisted out of
-      // the if-blocks below so doPush + doPull see the same set:
-      //
-      //   `HQ_SYNC_LOCAL_COMPANIES_TO_PERSONAL=1` opts INTO the
-      //   cloud:false → personal-bucket fallback. Default OFF keeps the
-      //   personal vault identical to the pre-5.20 shape until operators
-      //   explicitly enable it.
-      //
-      //   `teamSyncedSlugs` is the slug set the operator currently has
-      //   active team-bucket Memberships for, derived from the live plan.
-      //   Used by:
-      //     • push: filter `companies/` subdir enumeration so a team-synced
-      //       company never rides the personal slot; build
-      //       `decommissionPrefixes` so share() sweeps orphan keys for
-      //       any slug that's now team-backed.
-      //     • pull: filter `listRemoteFiles` so pre-decommission orphan
-      //       keys at `companies/{team-synced-slug}/...` don't get
-      //       re-downloaded into the disk paths the team-bucket pull
-      //       now manages.
-      const includeLocalCompanies =
-        process.env.HQ_SYNC_LOCAL_COMPANIES_TO_PERSONAL === "1";
-      const teamSyncedSlugs = new Set(
-        plan
-          .filter((p) => p.personalMode !== true)
-          .map((p) => p.slug),
-      );
-
-      // Resolve the membership's effective ACL scope ONCE so BOTH the push and
-      // pull legs respect the granted prefixes. The vault vends a child
-      // credential scoped to these prefixes; without filtering the PUSH plan to
-      // them, share() would HEAD/PUT keys outside the grant and the server's
-      // correct 403 (SCOPE_EXCEEDS_PARENT) would abort the WHOLE company with a
-      // generic error + exit 2. Personal-vault legs have no membership
-      // sync-config — they stay full-scope ("all"). Degrades to "all" on any
-      // error (a transient failure must never silently filter/prune the tree).
-      // Hoisted above the push block (it used to be resolved only for pull) so
-      // push gets the same scope; the pull leg below reuses this value.
-      const scope: PullScope =
-        target.personalMode === true
-          ? { syncMode: "all" }
-          : await resolvePullScope(
-              client,
-              target.uid,
-              target.slug,
-              parsed.hqRoot,
-            );
-
-      if (doPush) {
-        activePhase = "push";
-        // For the personal slot we hand share() both (a) the top-level
-        // hqRoot entries that are part of the personal vault and (b) any
-        // `companies/{slug}/` subdirs the user has opted into the personal
-        // bucket via `cloud: false` in `company.yaml`. Slugs that already
-        // own a team bucket (anything else in `plan`) are excluded so a
-        // company is never double-written.
-        const pushPaths = target.personalMode === true
-          ? computePersonalVaultPaths(parsed.hqRoot, {
-              includeLocalCompanies,
-              teamSyncedSlugs,
-            })
-          : [path.join(parsed.hqRoot, "companies", target.slug)];
-        // For the personal slot, hand share() a list of `companies/{slug}/`
-        // prefixes for every team-synced slug. If the personal-bucket
-        // journal still holds entries under any of those prefixes — i.e.
-        // the company used to ride the personal-bucket fallback and was
-        // since promoted to its own team bucket — share() will sweep
-        // those orphans via DeleteObject + journal removal. Unconditional
-        // (not gated on `HQ_SYNC_LOCAL_COMPANIES_TO_PERSONAL`) so cleanup
-        // still runs after an operator turns the feature off: the on-ramp
-        // is opt-in but the off-ramp is always safe to traverse.
-        const decommissionPrefixes = target.personalMode === true
-          ? Array.from(teamSyncedSlugs).map((slug) => `companies/${slug}`)
-          : undefined;
-        pushResult = await shareFn({
-          paths: pushPaths,
-          company: target.uid,
-          vaultConfig,
-          hqRoot: parsed.hqRoot,
-          onConflict: parsed.onConflict,
-          skipUnchanged: true,
-          // Local deletes propagate to S3 as soft deletes (versioning is on
-          // — DeleteObject writes a delete-marker, prior versions remain
-          // recoverable). Without this, a deleted file resurfaces on the
-          // next pull because the remote object is still listable.
-          //
-          // Policy default in 5.24 is `owned-only` (pre-5.24 behavior;
-          // preserved for the soak window). `HQ_SYNC_DELETE_POLICY` env
-          // can opt INTO the safer `currency-gated` (per-file HEAD + ETag
-          // verification) or the unsafe `all` (emergency reconcile only).
-          // Default flips to `currency-gated` in 5.25 after at least one
-          // machine has soaked the new path. Both personal and company
-          // targets use the same resolver — same engine, same flip.
-          propagateDeletes: true,
-          propagateDeletePolicy: resolveDeletePolicy(),
-          onEvent: tagAndEmit,
-          ...(uploadAuthor ? { author: uploadAuthor } : {}),
-          // Mirror the pull-side seam: only spread these for the personal
-          // slot so company-target args stay identical to the pre-Slice-2
-          // shape (the "no personalMode/journalSlug keys" regression test
-          // in sync-runner.test.ts pins that contract).
-          ...(target.personalMode !== undefined ? { personalMode: target.personalMode } : {}),
-          ...(target.journalSlug !== undefined ? { journalSlug: target.journalSlug } : {}),
-          ...(decommissionPrefixes && decommissionPrefixes.length > 0
-            ? { decommissionPrefixes }
-            : {}),
-          // US-005 symmetry: scope the PUSH plan to the membership's granted
-          // ACL prefixes so out-of-scope keys are skipped (and surfaced via a
-          // `scope-excluded` event) instead of drawing the server's 403 and
-          // aborting the company. `undefined` for `syncMode: "all"` (owner /
-          // personal) → no scope filter, identical to the pre-fix shape so the
-          // "company-target args" contract test stays green.
-          ...(scope.prefixSet !== undefined ? { prefixSet: scope.prefixSet } : {}),
-        });
-      }
-
-      // Pull runs unless the push phase aborted on conflict — aborted means
-      // the user has local edits + remote drift; blindly pulling would erase
-      // whichever side `--on-conflict abort` just protected.
-      if (doPull && !pushResult.aborted) {
-        activePhase = "pull";
-        // US-005: the pull only materializes in-scope keys (and prunes clean
-        // orphans when scope shrank). Reuse the `scope` resolved once above so
-        // push and pull apply the SAME granted prefixes and we avoid a second
-        // `listMyExplicitGrants` round-trip per company.
-        const pullScope: PullScope = scope;
-        pullResult = await syncFn({
-          company: target.uid,
-          vaultConfig,
-          hqRoot: parsed.hqRoot,
-          onConflict: parsed.onConflict,
-          syncMode: pullScope.syncMode,
-          // The menubar runner can take no interactive flag, so a scope shrink
-          // must NEVER throw here (the old `ScopeShrinkBlockedError` → exit 2
-          // was the permanent wedge in DEV-1768). Self-heal non-destructively:
-          // dirty out-of-scope files stay on disk + un-tracked, clean ones are
-          // quarantined (recoverable). This also clears an already-wedged
-          // journal — seeded by a buggy `all`-mode CLI pull — on the next sync.
-          scopeShrinkPolicy: "auto-recover",
-          // Scope-shrink authorship guard: pass the caller's own sub (the very
-          // sub stamped onto uploads as `created-by-sub`) so a scope shrink
-          // never prunes content this owner authored. Owners hold their whole
-          // vault by role-bypass, so without this a `shared`/`custom` pull
-          // would treat their own un-granted work as a foreign orphan.
-          ...(uploadAuthor?.userSub !== undefined
-            ? { callerSub: uploadAuthor.userSub }
-            : {}),
-          ...(pullScope.prefixSet !== undefined
-            ? { prefixSet: pullScope.prefixSet }
-            : {}),
-          ...(target.personalMode !== undefined ? { personalMode: target.personalMode } : {}),
-          ...(target.journalSlug !== undefined ? { journalSlug: target.journalSlug } : {}),
-          // Symmetric to the push side: for the personal slot, tell sync()
-          // how to interpret `companies/{slug}/...` keys in the personal
-          // bucket. With `includeLocalCompanies: true`, keys for slugs NOT
-          // in `teamSyncedSlugs` are downloaded (legitimate cloud:false
-          // opt-in content from another machine); keys for slugs IN that
-          // set are dropped as orphans (pre-decommission residue from a
-          // promoted company). With `includeLocalCompanies: false` the
-          // legacy pre-5.20 behavior holds: all `companies/...` keys are
-          // dropped. Only spread for the personal slot so company-target
-          // args stay identical to pre-Slice-2 shape (test C pin).
-          ...(target.personalMode === true
-            ? {
-                includeLocalCompanies,
-                teamSyncedSlugs,
-              }
-            : {}),
-          ...(deps.operationLockAlreadyHeld
-            ? { operationLockAlreadyHeld: true }
-            : {}),
-          onEvent: tagAndEmit,
-        });
-      }
-
-      // Concat push + pull conflict paths into a single per-company list,
-      // then dedupe — a key that legitimately conflicts on both halves of
-      // a bidirectional run (e.g. `.hq/install-manifest.json` round-trip
-      // before Fix #1) appears twice in the concat but represents a single
-      // logical conflict for the operator. Bug #3 in the 5.33.0 deep-test:
-      // every round produced `conflictPaths: [X, X]` and `conflicts: 2`,
-      // double-counting the conflict in every metric downstream. The push
-      // and pull halves each emit a `conflict` event in their own direction
-      // (preserved on the event stream for tracing); only the merged
-      // result list is collapsed. Stable first-seen order is preserved so
-      // consumers can rely on the pull entry coming before its push twin.
-      const seenConflictPaths = new Set<string>();
-      const mergedConflictPaths: string[] = [];
-      for (const p of [...pullResult.conflictPaths, ...pushResult.conflictPaths]) {
-        if (seenConflictPaths.has(p)) continue;
-        seenConflictPaths.add(p);
-        mergedConflictPaths.push(p);
-      }
-      const aborted = pullResult.aborted || pushResult.aborted;
-
-      // Overwrite the progress-derived counts with the authoritative numbers
-      // from the sync/share return values. The `progress` stream over-counts
-      // when the inner walker emits a progress row for a file it then skips
-      // due to a journal hit — a clean return value is the source of truth.
-      // For the throw case below this overwrite never runs, so `state` keeps
-      // its progress-derived counts (which is exactly what we want there).
-      state.filesDownloaded = pullResult.filesDownloaded;
-      state.bytesDownloaded = pullResult.bytesDownloaded;
-      state.filesUploaded = pushResult.filesUploaded;
-      state.bytesUploaded = pushResult.bytesUploaded;
-      state.status = companyHadTransferError
-        ? "errored"
-        : aborted
-          ? "aborted"
-          : "complete";
-
-      emit({
-        type: "complete",
-        company: companyLabel,
-        filesDownloaded: pullResult.filesDownloaded,
-        bytesDownloaded: pullResult.bytesDownloaded,
-        filesUploaded: pushResult.filesUploaded,
-        bytesUploaded: pushResult.bytesUploaded,
-        filesSkipped: pullResult.filesSkipped + pushResult.filesSkipped,
-        // Push-side counters surfaced on `complete` so the menubar's
-        // `SyncCompleteEvent` (which carries them as Option<u32> for
-        // back-compat with pre-5.25 engines) can render the new totals.
-        // Always emitted as numbers (0 when no push leg ran) so Rust's
-        // serde decodes them as `Some(0)` rather than `None` — distinct
-        // from the legacy-engine `None` and useful when the UI wants to
-        // distinguish "engine ran, nothing tombstoned" from "engine
-        // didn't report".
-        // Tombstones now flow on both legs:
-        //   - push side: `ShareResult.filesTombstoned` (remote was already
-        //     404 at HEAD time, journal entry dropped).
-        //   - pull side: `SyncResult.filesTombstoned` (Bug #9 — journal-
-        //     known key missing from remote LIST, applied as local delete).
-        // Sum them so the menubar's `SyncCompleteEvent` reflects the total
-        // delete-propagation activity for that company across the run.
-        filesTombstoned: pushResult.filesTombstoned + pullResult.filesTombstoned,
-        filesRefusedStale: pushResult.filesRefusedStale,
-        // Bonus diagnostic: surface the paths so operators can triage the
-        // recurring `filesRefusedStale: N` signal — the count alone was
-        // untriageable per the 5.33.0 deep-test report's "205 issue".
-        // Pre-capped at 50 by share() itself.
-        filesRefusedStalePaths: pushResult.filesRefusedStalePaths,
-        // Pull side now reports an `filesExcludedByPolicy` too (Bug #2 —
-        // ephemeral conflict-mirror refusals in the pull walker). Sum
-        // both legs so the `complete` event reports total excluded across
-        // the full bidirectional pass; pre-fix the pull half silently
-        // pushed legacy `.conflict-*` litter into clean trees with the
-        // same counter showing 0.
-        filesExcludedByPolicy:
-          pushResult.filesExcludedByPolicy + pullResult.filesExcludedByPolicy,
-        // Sourced from the merged path list so push-side conflicts are
-        // counted too — `ShareResult` doesn't expose a numeric counter,
-        // and using `pullResult.conflicts` alone silently dropped any
-        // push conflict from the count while leaving its path in
-        // `conflictPaths`.
-        conflicts: mergedConflictPaths.length,
-        conflictPaths: mergedConflictPaths,
-        // Either phase aborting marks the company aborted — the UI treats
-        // `aborted: true` as "sync didn't complete cleanly for this company".
-        aborted,
-        newFiles: pullResult.newFiles,
-        newFilesCount: pullResult.newFilesCount,
-        // Scope-aware download counters (US-005). Pull-only — the push leg
-        // has no scope concept — so they pass through from `pullResult`.
-        filesOutOfScope: pullResult.filesOutOfScope,
-        scopeOrphansRemoved: pullResult.scopeOrphansRemoved,
-        scopeOrphansBlocked: pullResult.scopeOrphansBlocked,
-      });
-      for (const p of pullResult.conflictPaths) {
-        allConflicts.push({ company: companyLabel, path: p, direction: "pull" });
-      }
-      for (const p of pushResult.conflictPaths) {
-        allConflicts.push({ company: companyLabel, path: p, direction: "push" });
-      }
-    } catch (err) {
-      // describeError walks the cause chain so AWS SDK v3's "UnknownError"
-      // wrapper surfaces the underlying Node networking error (ENOTFOUND,
-      // ECONNRESET, …) instead of an unactionable bare "UnknownError".
-      const message = describeError(err);
-      errors.push({ company: companyLabel, message });
-      // `state.status` was seeded as "errored" at loop entry — the throw
-      // path leaves it there, and `state.files{Down,Up}loaded` reflects the
-      // partial counts captured from `progress` events before the throw.
-      // Emit a `complete` event with `aborted: true` and those partial
-      // counts so consumers walking the `complete` event stream see every
-      // company in the fanout uniformly. This is the fix for the misleading
-      // rollup — see file header `Exit code: 2` doc.
-      emit({
-        type: "complete",
-        company: companyLabel,
-        filesDownloaded: state.filesDownloaded,
-        bytesDownloaded: state.bytesDownloaded,
-        filesUploaded: state.filesUploaded,
-        bytesUploaded: state.bytesUploaded,
-        filesSkipped: 0,
-        // Mid-flight throw: we have no clean ShareResult to read these
-        // from. Report 0 so the event shape stays stable; the partial
-        // counts above already reflect what actually moved before the
-        // throw.
-        filesTombstoned: 0,
-        filesRefusedStale: 0,
-        filesRefusedStalePaths: [],
-        filesExcludedByPolicy: 0,
-        conflicts: 0,
-        conflictPaths: [],
-        aborted: true,
-        newFiles: [],
-        newFilesCount: 0,
-        // Mid-flight throw: no clean scope counts to report. 0 keeps the
-        // event shape stable (US-005).
-        filesOutOfScope: 0,
-        scopeOrphansRemoved: 0,
-        scopeOrphansBlocked: 0,
-      });
-      emit({
-        type: "error",
-        company: companyLabel,
-        path: "(company)",
-        message,
-      });
-      // Continue — one company's failure shouldn't abort the whole fanout.
-    }
-  }
-
-  // Walk every per-company entry — the map holds one row per planned company,
-  // including ones that aborted via thrown exception. This is the fix for the
-  // bug where `all-complete` reported `filesDownloaded: 0` for an aborted
-  // personal-sync that had already emitted thousands of `progress` events:
-  // the rollup used to only sum companies that emitted a clean `complete`,
-  // which silently dropped partials when the sync function threw.
-  let totalDownloaded = 0;
-  let totalDownloadedBytes = 0;
-  let totalUploaded = 0;
-  let totalUploadedBytes = 0;
-  let partial = false;
-  const companies: Array<{
-    company: string;
-    status: CompanyStatus;
-    filesDownloaded: number;
-    bytesDownloaded: number;
-    filesUploaded: number;
-    bytesUploaded: number;
-  }> = [];
-  for (const target of plan) {
-    const s = stateByCompany.get(target.slug);
-    if (!s) continue; // unreachable — every plan entry seeds the map
-    totalDownloaded += s.filesDownloaded;
-    totalDownloadedBytes += s.bytesDownloaded;
-    totalUploaded += s.filesUploaded;
-    totalUploadedBytes += s.bytesUploaded;
-    if (s.status !== "complete") partial = true;
-    companies.push({
-      company: s.company,
-      status: s.status,
-      filesDownloaded: s.filesDownloaded,
-      bytesDownloaded: s.bytesDownloaded,
-      filesUploaded: s.filesUploaded,
-      bytesUploaded: s.bytesUploaded,
-    });
-  }
+  const fanout = await executeCompanyFanout({
+    plan,
+    direction: parsed.direction,
+    hqRoot: parsed.hqRoot,
+    onConflict: parsed.onConflict,
+    client,
+    vaultConfig,
+    ...(uploadAuthor ? { uploadAuthor } : {}),
+    ...(deps.operationLockAlreadyHeld ? { operationLockAlreadyHeld: true } : {}),
+    syncFn,
+    shareFn,
+    resolveDeletePolicy,
+    emit,
+  });
+  const { errors, allConflicts } = fanout;
+  const rollup = rollupAllComplete(plan, fanout.stateByCompany);
 
   // Fire telemetry collector before the all-complete emit so the cursor at
   // `~/.hq/telemetry-cursor.json` is consistent with what the menubar sees.
-  // Awaited fully — fire-and-forget would lose in-flight POSTs at process
-  // exit, and the previous 10s race was wrong: a first-run user with
-  // backlog (e.g. 60K Claude session events) takes well over 10s legitimately,
-  // and the race silently dropped the entire batch when it fired. Errors
-  // are swallowed inside `defaultCollectTelemetry`; per-request timeouts
-  // come from `VaultClient`'s retry loop (3 attempts × exponential backoff),
-  // which naturally bounds the outer wait.
-  const telemetryFn =
-    deps.collectTelemetry ??
-    (() => defaultCollectTelemetry(client, deps.createVaultClient !== undefined, parsed.hqRoot));
-  await telemetryFn().catch(() => undefined);
+  await emitTelemetry({
+    collectTelemetry: deps.collectTelemetry,
+    defaultCollectTelemetry: () =>
+      defaultCollectTelemetry(
+        client,
+        deps.createVaultClient !== undefined,
+        parsed.hqRoot,
+      ),
+  });
 
   emit({
     type: "all-complete",
     companiesAttempted: plan.length,
-    filesDownloaded: totalDownloaded,
-    bytesDownloaded: totalDownloadedBytes,
-    filesUploaded: totalUploaded,
-    bytesUploaded: totalUploadedBytes,
+    filesDownloaded: rollup.totalDownloaded,
+    bytesDownloaded: rollup.totalDownloadedBytes,
+    filesUploaded: rollup.totalUploaded,
+    bytesUploaded: rollup.totalUploadedBytes,
     conflictPaths: allConflicts,
     errors,
-    partial,
-    companies,
+    partial: rollup.partial,
+    companies: rollup.companies,
   });
 
   // Post-sync qmd reindex — runs AFTER `all-complete` is emitted so the
@@ -1674,7 +1090,10 @@ export async function runRunner(
   // pulled in (nothing to reindex otherwise) and not explicitly disabled.
   // Self-contained: shells out to the global `qmd` binary, no dependency on
   // any (possibly stale) script inside the synced HQ tree. See qmd-reindex.ts.
-  if (totalDownloaded > 0 && process.env.HQ_QMD_REINDEX_ON_SYNC !== "0") {
+  if (
+    rollup.totalDownloaded > 0 &&
+    process.env.HQ_QMD_REINDEX_ON_SYNC !== "0"
+  ) {
     try {
       reindexAfterSync(parsed.hqRoot);
     } catch {
@@ -1849,604 +1268,28 @@ export interface WatcherSurface {
   dispose(): void;
 }
 
-/**
- * Route a changed relative path to the push target that owns it.
- *
- * - `companies/<slug>/...` → a single-company push for `<slug>` (the targeted
- *   pass per PRD decision — push only the changed company, not a full
- *   `--companies` fanout).
- * - anything else under hqRoot → the personal target (a `--companies` push
- *   restricted to personal via the personal-vault scope; modeled here as the
- *   "personal" route the caller maps to the right argv).
- *
- * Returns `null` for paths the routing cannot attribute (defensive — the
- * watcher's filter already drops excluded top-levels, so this is belt-and-
- * suspenders for synthetic events).
- */
-export function routeChangeToTarget(
-  relPath: string,
-): { kind: "company"; slug: string } | { kind: "personal" } | null {
-  const norm = relPath.split(path.sep).join("/").replace(/^\.\//, "");
-  if (norm === "" || norm.startsWith("..")) return null;
-  const segments = norm.split("/").filter((s) => s.length > 0);
-  if (segments.length === 0) return null;
-  if (segments[0] === "companies") {
-    // companies/<slug>/... — need at least the slug segment to target.
-    if (segments.length < 2 || segments[1].length === 0) return null;
-    return { kind: "company", slug: segments[1] };
-  }
-  return { kind: "personal" };
-}
-
-/**
- * Build the argv for a targeted push pass from a routed change. The push runs
- * `--direction push` for just the routed target so a local edit propagates in
- * seconds without a full fanout. Company routes use `--company <slug>`;
- * personal routes use `--companies --direction push` (the personal-vault scope
- * is resolved inside runRunner's fanout; skipUnchanged no-ops the company
- * subtrees that didn't change). Inherits `--hq-root` / `--on-conflict` from
- * the base argv. Pure helper, exported for unit testing the routing→argv map.
- */
-export function buildTargetedPushArgv(
-  route: { kind: "company"; slug: string } | { kind: "personal" },
-  baseArgv: string[],
-): string[] {
-  const carried = carriedFlags(baseArgv);
-  if (route.kind === "company") {
-    return ["--company", route.slug, "--direction", "push", ...carried];
-  }
-  return ["--companies", "--direction", "push", ...carried];
-}
-
-type WatchRoute = NonNullable<ReturnType<typeof routeChangeToTarget>>;
-
-function routeKey(route: WatchRoute): string {
-  return route.kind === "company" ? `company:${route.slug}` : "personal";
-}
-
-function routesForBatch(batch: TreeChangeBatch): Map<string, WatchRoute> {
-  const routes = new Map<string, WatchRoute>();
-  for (const relPath of batch.paths.values()) {
-    const route = routeChangeToTarget(relPath);
-    if (!route) continue;
-    routes.set(routeKey(route), route);
-  }
-  return routes;
-}
-
-function buildFullFanoutPushArgv(baseArgv: string[]): string[] {
-  return ["--companies", "--direction", "push", ...carriedFlags(baseArgv)];
-}
-
-/**
- * Build the argv for a targeted PULL pass from a routed change (US-009 — the
- * receiver's pull-on-event path). Mirrors {@link buildTargetedPushArgv} but
- * with `--direction pull`: a peer device pushed a change, so this device pulls
- * just the affected company/subtree instead of waiting for the next
- * `--poll-remote-ms` cycle. Company routes use `--company <slug>`; personal
- * routes use `--companies` (the personal-vault scope is resolved inside
- * runRunner's fanout; skipUnchanged no-ops the subtrees that didn't change).
- * Inherits `--hq-root` / `--on-conflict` from the base argv. Pure helper,
- * exported for unit testing the event→argv map.
- */
-export function buildTargetedPullArgv(
-  route: { kind: "company"; slug: string } | { kind: "personal" },
-  baseArgv: string[],
-): string[] {
-  const carried = carriedFlags(baseArgv);
-  if (route.kind === "company") {
-    return ["--company", route.slug, "--direction", "pull", ...carried];
-  }
-  return ["--companies", "--direction", "pull", ...carried];
-}
-
 export async function runRunnerWithLoop(
   argv: string[],
   deps: RunnerLoopDeps = {},
 ): Promise<number> {
   const parsed = parseArgs(argv);
-  if (!argv.includes("--watch")) {
-    // One-shot cloud sync — take the per-root operation lock so it is mutually
-    // exclusive with rescue/reindex. If args don't parse, fall through to
-    // `runRunner` so it surfaces the parse error rather than us masking it
-    // with a lock failure.
-    if ("error" in parsed) return runRunner(argv);
-    // The actual sync pass — same seam the watch loop uses (deps.runPass),
-    // so a test can assert "waits for a short-lived holder, THEN proceeds to
-    // sync" without touching the network. Production passes `argv` to
-    // runRunner exactly as before. Regression guard for DEV-1772
-    // (feedback_28a1833f): instant-sync one-shots used to exit 17 and die on
-    // a lock conflict with the ~1-min reindex hook; they now WAIT (default)
-    // and proceed once the short holder releases.
-    const runOnce =
-      deps.runPass ??
-      ((passArgv: string[]) =>
-        runRunner(passArgv, { operationLockAlreadyHeld: true }));
-    try {
-      return await withOperationLock(parsed.hqRoot, "sync", () => runOnce(argv), {
-        timeoutSec: parsed.lockTimeoutSec,
-      });
-    } catch (err) {
-      if (err instanceof OperationLockedError) {
-        // The lock wait was BOUNDED and tripped (a holder never released
-        // within --lock-timeout / HQ_OP_LOCK_TIMEOUT). Surface it loudly on
-        // stderr and exit with the stable OPERATION_LOCKED_EXIT (17) so the
-        // spawner (menubar) can recognize a lock conflict and SCHEDULE A
-        // RETRY rather than treating it as a hard failure and silently giving
-        // up (DEV-1772). With the default (no bound) we never reach here — the
-        // one-shot waits indefinitely and proceeds.
-        process.stderr.write(err.message + "\n");
-        return OPERATION_LOCKED_EXIT;
-      }
-      throw err;
-    }
-  }
-  if ("error" in parsed) return runRunner(argv);
-  const sleep =
-    deps.sleep ??
-    ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
-  const runPass =
-    deps.runPass ??
-    ((passArgv: string[]) =>
-      runRunner(passArgv, { operationLockAlreadyHeld: true }));
-  const pollIdx = argv.indexOf("--poll-remote-ms");
-  const pollMs =
-    pollIdx >= 0 && argv[pollIdx + 1] ? Number(argv[pollIdx + 1]) : 600_000;
-  const eventPush = argv.includes("--event-push");
-  // In `--companies` mode the sync scope is companies/*/{knowledge,projects,…}
-  // (per .hqinclude), so the watcher must NOT apply the personal-vault
-  // top-level exclusions (PERSONAL_VAULT_EXCLUDED_TOP_LEVEL drops `companies/`
-  // and `workspace/`) — doing so would exclude exactly the paths being synced,
-  // and no local edit would ever trigger an instant push. The shared ignore
-  // stack (createIgnoreFilter / .hqignore / .hqinclude) already scopes the
-  // watch filter correctly in companies mode. personalMode is only for a
-  // personal-vault-as-root run, where companies/ et al. genuinely aren't synced.
-  const companiesMode = argv.includes("--companies");
-  const hqRoot = parsed.hqRoot;
-
-  // Strip the loop-only flags before delegating: the parser inside runRunner
-  // accepts --watch/--poll-remote-ms/--event-push, but we don't want a per-
-  // iteration pass to think it's re-entering watch mode.
-  const passArgv = argv.filter((a, i) => {
-    if (a === "--watch") return false;
-    if (a === "--poll-remote-ms") return false;
-    if (a === "--event-push") return false;
-    if (i > 0 && argv[i - 1] === "--poll-remote-ms") return false;
-    return true;
-  });
-
-  if (parsed.lockTimeoutSec === 0) {
-    try {
-      const handle = acquireOperationLock(hqRoot, "sync", {
-        timeoutSec: 0,
-        onWaitStart: () => undefined,
-      });
-      handle.release();
-    } catch (err) {
-      if (err instanceof OperationLockedError) {
-        process.stderr.write(err.message + "\n");
-        return OPERATION_LOCKED_EXIT;
-      }
-      throw err;
-    }
-  }
-
-  const runPassWithLock = async (passArgvForRun: string[]): Promise<number> => {
-    try {
-      const handle = acquireOperationLock(hqRoot, "sync", {
-        timeoutSec: 0,
-        onWaitStart: () => undefined,
-      });
-      try {
-        return await runPass(passArgvForRun);
-      } finally {
-        handle.release();
-      }
-    } catch (err) {
-      if (!(err instanceof OperationLockedError)) throw err;
-      if (parsed.lockTimeoutSec === 0) {
-        process.stderr.write(err.message + "\n");
-        return OPERATION_LOCKED_EXIT;
-      }
-    }
-
-    try {
-      return await withOperationLock(
-        hqRoot,
-        "sync",
-        () => runPass(passArgvForRun),
-        { timeoutSec: parsed.lockTimeoutSec },
-      );
-    } catch (err) {
-      if (err instanceof OperationLockedError) {
-        process.stderr.write(err.message + "\n");
-        return OPERATION_LOCKED_EXIT;
-      }
-      throw err;
-    }
-  };
-
-  // ---- shared pass queue -----------------------------------------------
-  // The poll loop, pull-on-event receiver, and watcher-triggered pushes all
-  // funnel through this queue so local/remote triggers never overlap, and a
-  // trigger arriving during an active pass runs immediately after it instead
-  // of being dropped.
-  let stopped = false;
-  let activePass: Promise<number> | null = null;
-  type QueuedPass = {
-    argv: string[];
-    resolve: (code: number) => void;
-    reject: (err: unknown) => void;
-  };
-  const pendingPasses: QueuedPass[] = [];
-  const resolveStoppedQueue = (): void => {
-    while (pendingPasses.length > 0) {
-      pendingPasses.shift()?.resolve(0);
-    }
-  };
-  const drainQueuedPasses = (): void => {
-    if (activePass !== null) return;
-    if (stopped) {
-      resolveStoppedQueue();
-      return;
-    }
-    const next = pendingPasses.shift();
-    if (!next) return;
-    const current = startGuardedPass(next.argv);
-    void current.then(next.resolve, next.reject);
-  };
-  const startGuardedPass = (passArgvForRun: string[]): Promise<number> => {
-    const current = stopped
-      ? Promise.resolve(0)
-      : runPassWithLock(passArgvForRun);
-    activePass = current;
-    void current
-      .finally(() => {
-        if (activePass === current) {
-          activePass = null;
-          drainQueuedPasses();
-        }
-      })
-      .catch(() => undefined);
-    return current;
-  };
-  const runGuarded = (passArgvForRun: string[]): Promise<number> => {
-    if (activePass === null && pendingPasses.length === 0) {
-      return startGuardedPass(passArgvForRun);
-    }
-
-    return new Promise<number>((resolve, reject) => {
-      pendingPasses.push({ argv: passArgvForRun, resolve, reject });
-      drainQueuedPasses();
-    });
-  };
-
-  // ---- event-push wiring (Phase 1) -------------------------------------
-  let watcher: WatcherSurface | null = null;
-  let driver: WatchPushDriver | null = null;
-  let detachSignal: (() => void) | null = null;
-  const pendingWatcherPaths = new Map<string, string>();
-  let pendingWatcherOriginalBatch: TreeChangeBatch | null = null;
-  let pendingWatcherBareChange = false;
-  let pendingWatcherOverflowed = false;
-  let pendingWatcherDroppedPaths = 0;
-  let pendingWatcherDroppedBytes = 0;
-  const addPendingWatcherChange = (
-    changedRelPath?: string,
-    batch?: TreeChangeBatch,
-  ): void => {
-    if (batch) {
-      pendingWatcherOriginalBatch =
-        pendingWatcherPaths.size === 0 &&
-        !pendingWatcherBareChange &&
-        !pendingWatcherOverflowed &&
-        !batch.overflowed
-          ? batch
-          : null;
-      for (const [absolutePath, relativePath] of batch.paths.entries()) {
-        pendingWatcherPaths.set(absolutePath, relativePath);
-      }
-      if (batch.overflowed) {
-        pendingWatcherOverflowed = true;
-        pendingWatcherDroppedPaths += batch.droppedPaths ?? 0;
-        pendingWatcherDroppedBytes += batch.droppedBytes ?? 0;
-      }
-      return;
-    }
-    if (changedRelPath) {
-      pendingWatcherOriginalBatch = null;
-      pendingWatcherPaths.set(path.join(hqRoot, changedRelPath), changedRelPath);
-      return;
-    }
-    pendingWatcherOriginalBatch = null;
-    pendingWatcherBareChange = true;
-  };
-  const takePendingWatcherChange = (): {
-    rel: string | null;
-    batch: TreeChangeBatch | null;
-  } => {
-    const batch =
-      pendingWatcherOriginalBatch !== null && !pendingWatcherOverflowed
-        ? pendingWatcherOriginalBatch
-        : pendingWatcherPaths.size > 0 || pendingWatcherOverflowed
-        ? {
-            paths: new Map(pendingWatcherPaths),
-            ...(pendingWatcherOverflowed
-              ? {
-                  overflowed: true,
-                  droppedPaths: pendingWatcherDroppedPaths,
-                  droppedBytes: pendingWatcherDroppedBytes,
-                }
-              : {}),
-          }
-        : null;
-    const rel = [...pendingWatcherPaths.values()][0] ?? null;
-    const fallbackRel = rel ?? (pendingWatcherBareChange ? null : null);
-    pendingWatcherPaths.clear();
-    pendingWatcherOriginalBatch = null;
-    pendingWatcherBareChange = false;
-    pendingWatcherOverflowed = false;
-    pendingWatcherDroppedPaths = 0;
-    pendingWatcherDroppedBytes = 0;
-    return { rel: fallbackRel, batch };
-  };
-  // ---- pull-on-event receiver (Phase 2, US-009) ------------------------
-  // Started after the watcher, disposed before the watcher (mirror of the
-  // PushTransport ordering). Dormant by default: the default factory returns
-  // a NoopPushReceiver, and even a real receiver stays dormant unless the
-  // per-tenant feature flag is on AND a queue URL is provisioned server-side.
-  let receiver: PushReceiver | null = null;
-  // ---- event-driven publish + pull (Phase 3, US-017/018/019) ------------
-  // Brought up asynchronously after the watcher when the rollout gate
-  // passes; null until ready (and stays null on startup failure → poll-only).
-  let eventSync: EventSyncHandles | null = null;
-
-  if (eventPush) {
-    const clock = deps.clock ?? systemClock;
-    const debounceMs = 2000;
-    const createWatcher =
-      deps.createWatcher ??
-      ((opts) =>
-        new TreeWatcher({
-          hqRoot: opts.hqRoot,
-          debounceMs: opts.debounceMs,
-          clock: opts.clock,
-          // false in --companies mode so the watch filter matches the sync
-          // scope (companies/* are included via .hqinclude); true only for a
-          // personal-vault-as-root run.
-          personalMode: !companiesMode,
-        }));
-    watcher = createWatcher({ hqRoot, debounceMs, clock });
-
-    // The driver runs the targeted push when a debounced burst settles. Its
-    // concurrency guard collapses a trigger that lands mid-pass; we ALSO gate
-    // through `runGuarded` so a poll pass in flight is never overlapped.
-    driver = new WatchPushDriver({
-      debounceMs: 0, // TreeWatcher already debounces; the driver just guards.
-      clock,
-      push: async () => {
-        if (stopped) return;
-        // Snapshot accumulated watcher work BEFORE the await. Changes landing
-        // mid-pass are accumulated for the NEXT pass instead of overwriting
-        // this pass's publish target.
-        const { rel, batch: batchForPublish } = takePendingWatcherChange();
-        const batchRoutes = batchForPublish
-          ? routesForBatch(batchForPublish)
-          : new Map<string, WatchRoute>();
-        let targetedArgv: string[];
-        if (batchForPublish?.overflowed || batchRoutes.size > 1) {
-          targetedArgv = buildFullFanoutPushArgv(passArgv);
-        } else {
-          const route =
-            batchRoutes.size === 1
-              ? [...batchRoutes.values()][0]
-              : rel
-                ? routeChangeToTarget(rel)
-                : { kind: "personal" as const };
-          if (!route) return;
-          targetedArgv = buildTargetedPushArgv(route, passArgv);
-        }
-        const result = await runGuarded(targetedArgv);
-        // Phase 3 (US-017): publish PushEvents only AFTER the targeted push
-        // pass succeeded — an event must never announce bytes that are not
-        // in S3 yet. A failed pass publishes nothing; queued passes run after
-        // the active pass instead of dropping the watcher-triggered push. Fall
-        // back to a single-path batch when the watcher emitted a bare path
-        // signal. Overflowed batches deliberately publish nothing because the
-        // exact path set was dropped; the full fanout push plus cadence poll is
-        // the resync signal.
-        if (result === 0 && !stopped && eventSync && !batchForPublish?.overflowed) {
-          const batch: TreeChangeBatch | null =
-            batchForPublish ??
-            (rel ? { paths: new Map([[path.join(hqRoot, rel), rel]]) } : null);
-          if (batch) eventSync.publishBatch(batch);
-        }
-      },
-    });
-
-    // A debounced TreeWatcher 'changed' signal feeds the driver, which fires
-    // the targeted push after its own (zero) window — i.e. immediately, but
-    // still serialized behind any in-flight pass. A path-aware watcher passes
-    // the changed relative path so the push targets just its owning company;
-    // the bare-signal TreeWatcher leaves it null → personal-vault route.
-    watcher.onChange((changedRelPath, batch) => {
-      if (stopped) return;
-      addPendingWatcherChange(changedRelPath, batch);
-      driver?.notifyChange();
-    });
-    watcher.start();
-
-    // Pull-on-event receiver (US-009). The injected SyncEngineFn bridges a
-    // received PushEvent → a TARGETED pull pass routed by relativePath, funneled
-    // through the SAME `runGuarded` mutex as the poll loop + watcher push so a
-    // pull-on-event never overlaps an in-flight pass. Started AFTER the watcher
-    // so a live event can't race a half-built daemon. Default factory = noop
-    // (dormant); a real SqsPushReceiver is injected by a later release once the
-    // server-side per-client SQS queue is provisioned.
-    const receiverSyncFn: SyncEngineFn = async (ctx) => {
-      if (stopped) return;
-      const route = routeChangeToTarget(ctx.event.relativePath);
-      if (!route) return;
-      const targetedArgv = buildTargetedPullArgv(route, passArgv);
-      const result = await runGuarded(targetedArgv);
-      if (result !== 0) {
-        throw new Error(`targeted pull failed with exit code ${result}`);
-      }
-    };
-    const createReceiver =
-      deps.createReceiver ?? (() => new NoopPushReceiver());
-    receiver = createReceiver({ syncFn: receiverSyncFn, hqRoot });
-    // Fire-and-forget start: a receiver's start() kicks off its own poll loop
-    // (SqsPushReceiver) or trivially flips connected (noop) — it must NOT block
-    // the runner's poll loop from entering. Errors are swallowed; the cadence
-    // poll is the safety net regardless of receiver health. (The await-free
-    // start also keeps the poll loop's microtask timing identical to the
-    // pre-US-009 wiring.)
-    void Promise.resolve(receiver.start()).catch(() => undefined);
-
-    // ---- Phase 3: event-driven publish + pull (US-017/018/019) ----------
-    // Gated to enrolled accounts (resolveEventSync — exact-email allowlist +
-    // HQ_SYNC_EVENT_SYNC override). Brought up asynchronously so a slow
-    // subscribe/vend can't delay the first poll pass; until (and unless) the
-    // handles resolve, behavior is byte-identical to the gate-off path.
-    const getClaims = deps.getIdTokenClaims ?? defaultGetIdTokenClaims;
-    const email = getClaims()?.email;
-    if (resolveEventSync(email, process.env.HQ_SYNC_EVENT_SYNC)) {
-      const getAccessToken =
-        deps.getAccessToken ??
-        (() => getValidAccessToken(DEFAULT_COGNITO, { interactive: false }));
-      const startES = deps.startEventSync ?? defaultStartEventSync;
-      // Entirely async + caught: NOTHING in the Phase 3 bring-up (device-id
-      // persistence, tenant resolution, subscribe) may crash or delay the
-      // daemon — any failure degrades to poll-only.
-      void (async () => {
-        const handles = await startES({
-          hqRoot,
-          apiUrl: DEFAULT_VAULT_API_URL,
-          authToken: getAccessToken,
-          deviceId: getOrCreateMachineId(hqRoot),
-          // The server rejects publishes whose originTenantId mismatches the
-          // JWT principal, so resolve the SAME canonical person uid the vault
-          // API derives from this token.
-          resolveTenantId: async () => {
-            const client = new VaultClient({
-              apiUrl: DEFAULT_VAULT_API_URL,
-              authToken: getAccessToken,
-              region: DEFAULT_COGNITO.region,
-            });
-            const persons = await client.entity.listByType("person");
-            const pick = pickCanonicalPersonEntity(persons);
-            if (!pick?.uid) {
-              throw new Error("no canonical person entity for this account");
-            }
-            return pick.uid;
-          },
-          syncFn: receiverSyncFn,
-          log: (m) => process.stderr.write(`${m}\n`),
-        });
-        if (!handles) return;
-        if (stopped) {
-          // Shutdown raced the async bring-up — tear straight down.
-          void handles.dispose();
-          return;
-        }
-        eventSync = handles;
-      })().catch((err) => {
-        process.stderr.write(
-          `event-sync: wiring failed, continuing poll-only: ${describeError(err)}\n`,
-        );
-      });
-    }
-  }
-
-  // ---- clean shutdown --------------------------------------------------
-  // SIGTERM (menubar stop_daemon) / SIGINT must tear down BOTH the watcher and
-  // the poll loop with no leaked timers or fds. We flip `stopped`, dispose the
-  // watcher + driver, and let the poll loop observe `stopped` on its next tick.
-  let resolveStopped: (() => void) | null = null;
-  const stoppedSignal = new Promise<void>((resolve) => {
-    resolveStopped = resolve;
-  });
-  const shutdown = (): void => {
-    if (stopped) return;
-    stopped = true;
-    resolveStoppedQueue();
-    // Dispose the receiver FIRST (mirror of the PushTransport ordering:
-    // inbound subscription torn down before the watcher) so no new
-    // pull-on-event fires mid-teardown. dispose() is async (it drains the
-    // in-flight pull up to its own deadline); fire-and-forget here — the
-    // receiver's internal drain + the runGuarded mutex bound the work, and
-    // SIGTERM teardown must not block. Errors are swallowed.
-    try {
-      void receiver?.dispose();
-    } catch {
-      /* ignore */
-    }
-    // Phase 3 wiring (publish transport + live receiver) — torn down with
-    // the same fire-and-forget posture as the Phase 2 receiver above.
-    try {
-      void eventSync?.dispose();
-    } catch {
-      /* ignore */
-    }
-    eventSync = null;
-    try {
-      driver?.dispose();
-    } catch {
-      /* ignore */
-    }
-    try {
-      watcher?.dispose();
-    } catch {
-      /* ignore */
-    }
-    resolveStopped?.();
+  const runtime = {
+    runPassWithOperationLockAlreadyHeld: (passArgv: string[]) =>
+      runRunner(passArgv, { operationLockAlreadyHeld: true }),
+    defaultGetIdTokenClaims,
+    defaultGetAccessToken: () =>
+      getValidAccessToken(DEFAULT_COGNITO, { interactive: false }),
+    apiUrl: DEFAULT_VAULT_API_URL,
+    region: DEFAULT_COGNITO.region,
   };
-  const onShutdownSignal =
-    deps.onShutdownSignal ??
-    ((handler: () => void) => {
-      const wrapped = () => handler();
-      process.on("SIGTERM", wrapped);
-      process.on("SIGINT", wrapped);
-      return () => {
-        process.off("SIGTERM", wrapped);
-        process.off("SIGINT", wrapped);
-      };
-    });
-  detachSignal = onShutdownSignal(shutdown);
 
-  try {
-    while (!stopped) {
-      const result = await runGuarded(passArgv);
-      if (result !== 0) {
-        return result;
-      }
-      // Sleep the poll interval, but wake early on shutdown so SIGTERM stops
-      // the loop promptly instead of waiting out a 10-minute cycle.
-      await Promise.race([sleep(pollMs), stoppedSignal]);
-    }
-    return 0;
-  } finally {
-    shutdown();
-    detachSignal?.();
+  if (!argv.includes("--watch")) {
+    if ("error" in parsed) return runRunner(argv);
+    return runOneShotWithOperationLock(argv, parsed, deps, runtime);
   }
-}
 
-/**
- * Extract the `--hq-root` / `--on-conflict` pair-flags from a base argv so a
- * re-targeted push pass inherits the same root and conflict policy. Pure
- * helper used by the event-push targeted-push composer.
- */
-function carriedFlags(baseArgv: string[]): string[] {
-  const carried: string[] = [];
-  for (let i = 0; i < baseArgv.length; i++) {
-    const a = baseArgv[i];
-    if (a === "--hq-root" || a === "--on-conflict") {
-      carried.push(a);
-      if (baseArgv[i + 1] !== undefined) carried.push(baseArgv[++i]);
-    }
-  }
-  return carried;
+  if ("error" in parsed) return runRunner(argv);
+  return runWatchLoop(argv, parsed, deps, runtime);
 }
 
 if (isDirectInvocation) {