@indigoai-us/hq-cloud 5.25.0 → 5.27.0

package/.github/workflows/ci.yml

@@ -21,3 +21,37 @@ jobs:
       - run: pnpm run build
       - run: pnpm run typecheck
       - run: pnpm test
+
+  # ─────────────────────────────────────────────────────────────────────────
+  # US-010 — Cross-tenant isolation invariant (BLOCKING)
+  # ─────────────────────────────────────────────────────────────────────────
+  # Runs the e2e that pins the P0 client-side invariant: NO tenant-A data may
+  # ever reach a tenant-B device via the event-driven push OR pull path. The
+  # job runs on every pull_request (the workflow trigger above). A FAILURE IS
+  # A P0 incident — do not merge/deploy/flag-flip until green again (see the
+  # test file's header banner and the project journal).
+  #
+  # Mirrors hq-pro PR #112's server-side `cross-tenant-isolation` gate on the
+  # hq-cloud CLIENT side. Runs in parallel with `build` (no `needs:`) so a
+  # security-invariant regression surfaces independent of any unrelated build
+  # noise. The test lives under test/ and is run via the project's `test:e2e`
+  # script (vitest run test/), narrowed to this one file so the gate is fast
+  # and unambiguous.
+  cross-tenant-isolation:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile --config.minimumReleaseAge=1440
+      # Fail-fast: a broken type surface would make the e2e run produce a
+      # confusing runtime error — typecheck up front so this BLOCKING job
+      # fails loudly and early instead.
+      - run: pnpm run typecheck
+      - name: Cross-tenant isolation E2E (blocking)
+        run: pnpm vitest run test/e2e/sync/cross-tenant-isolation.test.ts

package/dist/bin/sync-runner.d.ts

@@ -59,6 +59,8 @@ import { type VaultServiceConfig, type Membership, type EntityInfo, type Pending
 import { PERSONAL_VAULT_EXCLUDED_TOP_LEVEL, computePersonalVaultPaths } from "../personal-vault.js";
 import type { SyncOptions, SyncResult, SyncProgressEvent } from "../cli/sync.js";
 import type { ShareOptions, ShareResult } from "../cli/share.js";
+import { type Clock } from "../watcher.js";
+import { type PushReceiver, type SyncEngineFn } from "../sync/push-receiver.js";
 /**
  * Sync direction for a run.
  *
@@ -324,5 +326,140 @@ export declare function runRunner(argv: string[], deps?: RunnerDeps): Promise<nu
  * exit 0 today and so will retry — acceptable noise for the beta; deal with
  * it via a richer return shape if it shows up in Sentry.
  */
-export declare function runRunnerWithLoop(argv: string[]): Promise<number>;
+/**
+ * Test/event-driven seam (US-001).
+ *
+ * `runRunnerWithLoop` performs an unbounded poll loop in production. To make
+ * the loop deterministically testable (US-003 wires the event-driven watcher
+ * into this same loop), the inter-pass sleep is injectable via `deps.sleep`.
+ * The default uses the host timer and preserves exact production behavior.
+ *
+ * A test (or US-003's wiring) injects a fake sleep that resolves immediately
+ * and/or coordinates with the {@link WatchPushDriver} seam in `../watcher.js`,
+ * so the loop can be exercised without a real 10-minute wait.
+ */
+export interface RunnerLoopDeps {
+    /** Sleep `ms` between passes. Default: host setTimeout. */
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * Run a single sync pass. Defaults to {@link runRunner}. Injected by tests
+     * (and the event-push wiring) so the poll loop and the watcher-triggered
+     * targeted push share one seam and one in-flight guard. The default ignores
+     * `deps` and forwards just the argv to `runRunner`.
+     */
+    runPass?: (passArgv: string[]) => Promise<number>;
+    /**
+     * Clock seam for the event-push watcher's debounce window. Defaults to
+     * {@link systemClock}; tests inject a `FakeClock` to advance the window
+     * deterministically. Only consulted when `--event-push` is on.
+     */
+    clock?: Clock;
+    /**
+     * Factory for the file watcher used in event-push mode. Defaults to a real
+     * {@link TreeWatcher} over `hqRoot`. Tests inject a stub exposing the same
+     * `onChange`/`start`/`stop`/`dispose` surface so no real chokidar runs.
+     */
+    createWatcher?: (opts: {
+        hqRoot: string;
+        debounceMs: number;
+        clock: Clock;
+    }) => WatcherSurface;
+    /**
+     * Register a one-shot shutdown signal handler. Defaults to listening for
+     * SIGTERM/SIGINT on `process`. Tests inject a controllable trigger to assert
+     * clean teardown without sending real signals. The returned fn detaches the
+     * handler (called during teardown so tests don't leak listeners).
+     */
+    onShutdownSignal?: (handler: () => void) => () => void;
+    /**
+     * Factory for the Phase 2 pull-on-event receiver (US-009). Defaults to a
+     * {@link NoopPushReceiver} — the daemon ships the receiver SEAM wired into
+     * the lifecycle (start after the watcher, dispose before exit) but stays
+     * DORMANT by default: the per-client SQS queue is provisioned server-side
+     * (an unbuilt follow-up) and the receiver is feature-flag gated. A future
+     * menubar/CLI release injects an {@link SqsPushReceiver} here once a queue
+     * URL is available. Only consulted when `--event-push` is on.
+     *
+     * The factory is handed a {@link SyncEngineFn} that bridges a received
+     * PushEvent to a TARGETED pull pass (`--company <slug> --direction pull`,
+     * or a personal `--companies --direction pull`) routed by the event's
+     * `relativePath`, funneled through the same in-flight guard as the poll
+     * loop and the watcher push so a pull-on-event never overlaps an in-flight
+     * pass.
+     */
+    createReceiver?: (opts: {
+        syncFn: SyncEngineFn;
+        hqRoot: string;
+    }) => PushReceiver;
+}
+/**
+ * The minimal watcher surface the loop drives. {@link TreeWatcher} satisfies
+ * it; tests inject a lighter stub. Kept narrow so the loop never reaches past
+ * the lifecycle + change-subscription contract.
+ *
+ * `onChange`'s listener receives an OPTIONAL changed relative path. The real
+ * {@link TreeWatcher} emits a bare debounced signal (no path) — in that case
+ * the loop routes the targeted push to the personal vault. A path-aware
+ * watcher (or a test stub) can pass the changed `companies/<slug>/...`
+ * relative path so the loop targets just that company.
+ */
+export interface WatcherSurface {
+    onChange(listener: (changedRelPath?: string) => void): () => void;
+    start(): void;
+    stop(): void;
+    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 declare function routeChangeToTarget(relPath: string): {
+    kind: "company";
+    slug: string;
+} | {
+    kind: "personal";
+} | null;
+/**
+ * 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 declare function buildTargetedPushArgv(route: {
+    kind: "company";
+    slug: string;
+} | {
+    kind: "personal";
+}, baseArgv: string[]): string[];
+/**
+ * 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 declare function buildTargetedPullArgv(route: {
+    kind: "company";
+    slug: string;
+} | {
+    kind: "personal";
+}, baseArgv: string[]): string[];
+export declare function runRunnerWithLoop(argv: string[], deps?: RunnerLoopDeps): Promise<number>;
 //# sourceMappingURL=sync-runner.d.ts.map

package/dist/bin/sync-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync-runner.d.ts","sourceRoot":"","sources":["../../src/bin/sync-runner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sync-runner.d.ts","sourceRoot":"","sources":["../../src/bin/sync-runner.ts"],"names":[],"mappings":"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"}

package/dist/bin/sync-runner.js

@@ -65,6 +65,8 @@ import { PERSONAL_VAULT_EXCLUDED_TOP_LEVEL, computePersonalVaultPaths, } from ".
 import { sync as defaultSync } from "../cli/sync.js";
 import { share as defaultShare } from "../cli/share.js";
 import { collectAndSendTelemetry } from "../telemetry.js";
+import { TreeWatcher, WatchPushDriver, systemClock, } from "../watcher.js";
+import { NoopPushReceiver, } from "../sync/push-receiver.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
@@ -190,6 +192,7 @@ function parseArgs(argv) {
     let watch = false;
     let pollRemoteMs;
     let skipPersonal = false;
+    let eventPush = false;
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         switch (arg) {
@@ -251,6 +254,12 @@ function parseArgs(argv) {
                 // resolveSkipPersonal().
                 skipPersonal = true;
                 break;
+            case "--event-push":
+                // Phase 1 event-driven push enable flag. Requires --watch (validated
+                // below). Gated OFF by default; the menubar only passes it for
+                // @getindigo.ai identities for the first release.
+                eventPush = true;
+                break;
             default:
                 return { error: `Unknown argument: ${arg}` };
         }
@@ -264,7 +273,20 @@ function parseArgs(argv) {
     if (pollRemoteMs !== undefined && !watch) {
         return { error: "--poll-remote-ms requires --watch" };
     }
-    return { companies, company, onConflict, hqRoot, direction, watch, pollRemoteMs, skipPersonal };
+    if (eventPush && !watch) {
+        return { error: "--event-push requires --watch" };
+    }
+    return {
+        companies,
+        company,
+        onConflict,
+        hqRoot,
+        direction,
+        watch,
+        pollRemoteMs,
+        skipPersonal,
+        eventPush,
+    };
 }
 // ---------------------------------------------------------------------------
 // Telemetry default — closes over the runner's vault client. Skipped when
@@ -831,37 +853,287 @@ const isDirectInvocation = (() => {
     }
 })();
 /**
- * Auto-sync (Beta) watch loop. Re-runs the one-shot runner every
- * `pollRemoteMs` until the process is killed (SIGTERM from the menubar's
- * stop_daemon command) or until a pass returns a non-zero exit code (hard
- * error worth surfacing to the operator). `setup-needed` and `auth-error`
- * exit 0 today and so will retry — acceptable noise for the beta; deal with
- * it via a richer return shape if it shows up in Sentry.
+ * 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 async function runRunnerWithLoop(argv) {
+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 = {}) {
     if (!argv.includes("--watch")) {
         return runRunner(argv);
     }
+    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;
-    // Strip --watch / --poll-remote-ms before delegating: the parser inside
-    // runRunner accepts them, but we don't want runRunner to think it's
-    // re-entering watch mode each iteration.
+    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;
     });
-    while (true) {
-        const code = await runRunner(passArgv);
-        if (code !== 0)
-            return code;
-        await new Promise((resolve) => setTimeout(resolve, pollMs));
+    // ---- 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;
+    // ---- 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;
+    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;
+                const route = rel
+                    ? routeChangeToTarget(rel)
+                    : { kind: "personal" };
+                if (!route)
+                    return;
+                const targetedArgv = buildTargetedPushArgv(route, passArgv);
+                await runGuarded(() => runPass(targetedArgv));
+            },
+        });
+        // 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) => {
+            if (stopped)
+                return;
+            lastChangedRel = changedRelPath ?? 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);
+    }
+    // ---- 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 */
+        }
+        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 carried;
 }
 if (isDirectInvocation) {
     runRunnerWithLoop(process.argv.slice(2))