@indigoai-us/hq-cloud 6.11.11 → 6.11.13

package/dist/bin/sync-runner.js

@@ -71,13 +71,15 @@ 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 { withOperationLock, OperationLockedError, OPERATION_LOCKED_EXIT, } from "../operation-lock.js";
-import { describeError } from "../lib/describe-error.js";
 import { getOrCreateMachineId } from "../lib/machine-id.js";
-import { TreeWatcher, WatchPushDriver, systemClock, } from "../watcher.js";
-import { NoopPushReceiver, } from "../sync/push-receiver.js";
-import { resolveEventSync, startEventSync as defaultStartEventSync, } from "../sync/event-sync.js";
-import { PERSONAL_VAULT_JOURNAL_SLUG, migratePersonalVaultJournal, } from "../journal.js";
+import { migratePersonalVaultJournal } from "../journal.js";
+import { createRunnerEmitter } from "./sync-runner-events.js";
+import { 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";
 // ---------------------------------------------------------------------------
 // Defaults — mirror `hq-cli/src/utils/cognito-session.ts`. Inlined (not
 // imported) to avoid a circular dep between hq-cli and hq-cloud. If these
@@ -528,14 +530,7 @@ export async function runRunner(argv, deps = {}) {
     // 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 = new Set([
-        "error",
-        "auth-error",
-    ]);
-    const emit = (event) => {
-        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);
     if ("error" in parsed) {
@@ -619,37 +614,21 @@ export async function runRunner(argv, deps = {}) {
     // ---- resolve targets --------------------------------------------------
     let memberships;
     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) {
@@ -669,64 +648,20 @@ export async function runRunner(argv, deps = {}) {
         });
         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 = [];
-    for (const m of memberships) {
-        let slug = m.companyUid;
-        let name;
-        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;
     }
-    emit({ type: "fanout-plan", companies: plan });
+    const plan = targetPlan.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
     // does NOT trigger a mass re-upload of the HQ overlay on first run. No-op
@@ -736,495 +671,39 @@ export async function runRunner(argv, deps = {}) {
     // ---- 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 = [];
-    const allConflicts = [];
-    const stateByCompany = new Map();
-    for (const target of plan) {
-        const companyLabel = target.slug;
-        const state = {
-            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 = 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.
-        const tagAndEmit = (event) => {
-            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") {
-                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 = {
-                filesUploaded: 0,
-                bytesUploaded: 0,
-                filesSkipped: 0,
-                filesDeleted: 0,
-                filesTombstoned: 0,
-                filesRefusedStale: 0,
-                filesRefusedStalePaths: [],
-                filesSuppressedByTombstone: 0,
-                filesExcludedByPolicy: 0,
-                filesExcludedByScope: 0,
-                conflictPaths: [],
-                aborted: false,
-            };
-            let pullResult = {
-                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 = 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 = 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,
-                        }
-                        : {}),
-                    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();
-            const mergedConflictPaths = [];
-            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 = 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 = [];
-    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
     // menubar/CLI already shows the sync as done; this is a best-effort tail
@@ -1232,7 +711,8 @@ export async function runRunner(argv, deps = {}) {
     // 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);
         }
@@ -1290,405 +770,23 @@ const isDirectInvocation = (() => {
         return false;
     }
 })();
-/**
- * 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) {
-    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, baseArgv) {
-    const carried = carriedFlags(baseArgv);
-    if (route.kind === "company") {
-        return ["--company", route.slug, "--direction", "push", ...carried];
-    }
-    return ["--companies", "--direction", "push", ...carried];
-}
-/**
- * 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, baseArgv) {
-    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, deps = {}) {
+    const parsed = parseArgs(argv);
+    const runtime = {
+        runPassWithOperationLockAlreadyHeld: (passArgv) => runRunner(passArgv, { operationLockAlreadyHeld: true }),
+        defaultGetIdTokenClaims,
+        defaultGetAccessToken: () => getValidAccessToken(DEFAULT_COGNITO, { interactive: false }),
+        apiUrl: DEFAULT_VAULT_API_URL,
+        region: DEFAULT_COGNITO.region,
+    };
     if (!argv.includes("--watch")) {
-        // One-shot cloud sync — take the per-root operation lock so it is mutually
-        // exclusive with rescue/reindex. The `--watch` path below is the push
-        // watcher and is intentionally EXEMPT (it neither takes nor is blocked by
-        // the lock; its in-process targeted passes call `runRunner` directly, not
-        // through here). If args don't parse, fall through to `runRunner` so it
-        // surfaces the parse error rather than us masking it with a lock failure.
-        const parsed = parseArgs(argv);
         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) => runRunner(passArgv));
-        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;
-        }
-    }
-    const sleep = deps.sleep ??
-        ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
-    const runPass = deps.runPass ?? ((passArgv) => runRunner(passArgv));
-    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 hqIdx = argv.indexOf("--hq-root");
-    const hqRoot = hqIdx >= 0 && argv[hqIdx + 1] ? argv[hqIdx + 1] : DEFAULT_HQ_ROOT;
-    // 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;
-    });
-    // ---- shared in-flight guard ------------------------------------------
-    // The poll loop AND watcher-triggered targeted pushes funnel through this
-    // mutex so a watcher push never overlaps an in-flight pass (PRD AC). A
-    // trigger that arrives while a pass runs is collapsed by WatchPushDriver's
-    // own pending-while-pushing logic, then re-armed after the pass settles.
-    let inFlight = false;
-    let stopped = false;
-    const runGuarded = async (pass) => {
-        if (inFlight)
-            return "skipped";
-        inFlight = true;
-        try {
-            return await pass();
-        }
-        finally {
-            inFlight = false;
-        }
-    };
-    // ---- event-push wiring (Phase 1) -------------------------------------
-    let watcher = null;
-    let driver = null;
-    let detachSignal = null;
-    let lastChangedRel = null;
-    let lastBatch = null;
-    // ---- 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 = 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 = 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;
-                const rel = lastChangedRel;
-                // Snapshot the settled batch BEFORE the await: a change landing
-                // mid-pass overwrites lastBatch for the NEXT pass, and this pass
-                // must only announce what it actually pushed.
-                const batchForPublish = lastBatch;
-                lastBatch = null;
-                const route = rel
-                    ? routeChangeToTarget(rel)
-                    : { kind: "personal" };
-                if (!route)
-                    return;
-                const targetedArgv = buildTargetedPushArgv(route, passArgv);
-                const result = await runGuarded(() => runPass(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 skipped pass (guard held) or a failed pass publishes
-                // nothing; the cadence poll covers the miss. Fall back to a
-                // single-path batch when the watcher emitted a bare path signal.
-                if (result === 0 && eventSync) {
-                    const batch = 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;
-            lastChangedRel = changedRelPath ?? null;
-            lastBatch = batch ?? null;
-            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 = async (ctx) => {
-            if (stopped)
-                return;
-            const route = routeChangeToTarget(ctx.event.relativePath);
-            if (!route)
-                return;
-            const targetedArgv = buildTargetedPullArgv(route, passArgv);
-            await runGuarded(() => runPass(targetedArgv));
-        };
-        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 = null;
-    const stoppedSignal = new Promise((resolve) => {
-        resolveStopped = resolve;
-    });
-    const shutdown = () => {
-        if (stopped)
-            return;
-        stopped = true;
-        // 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 onShutdownSignal = deps.onShutdownSignal ??
-        ((handler) => {
-            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(() => runPass(passArgv));
-            // A poll pass that was skipped because a watcher push held the guard is
-            // benign — the next iteration retries after the poll interval.
-            if (typeof result === "number" && 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?.();
-    }
-}
-/**
- * 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) {
-    const carried = [];
-    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 runOneShotWithOperationLock(argv, parsed, deps, runtime);
     }
-    return carried;
+    if ("error" in parsed)
+        return runRunner(argv);
+    return runWatchLoop(argv, parsed, deps, runtime);
 }
 if (isDirectInvocation) {
     runRunnerWithLoop(process.argv.slice(2))