@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/bin/sync-runner.ts

@@ -1,2190 +0,0 @@
-#!/usr/bin/env node
-/**
- * hq-sync-runner — machine-targeted entrypoint for `@indigoai-us/hq-cloud`
- * (ADR-0001).
- *
- * The AppBar Sync menubar (Tauri + Rust) spawns this binary as a subprocess
- * and reads ndjson events from BOTH stdout and stderr (see "Channels"
- * below). The protocol is intentionally narrow and versioned-by-shape, not
- * by tooling — no chalk, no colors, no human prose. If you want to invoke
- * sync as a human, use `hq sync` in `@indigoai-us/hq-cli`.
- *
- * Flags:
- *   --companies               Fan out across every membership the caller has
- *   --company <slug-or-uid>   Sync a single company (alternative to --companies)
- *   --on-conflict <strategy>  abort | overwrite | keep (default: abort)
- *   --hq-root <path>          Local HQ directory (default: $HOME/hq)
- *   --skip-personal           Drop the personal target from the --companies
- *                             fanout. Combined with HQ_SYNC_SKIP_PERSONAL env
- *                             (either truthy disables personal sync). No-op
- *                             outside --companies mode.
- *   --json                    Ignored — ndjson on stdout is the default and
- *                             only output mode. Accepted for symmetry with the
- *                             AppBar's argv in case someone passes it.
- *
- * Channels (one JSON object per line):
- *   stdout — protocol stream:
- *     setup-needed   caller signed in but has no person entity yet
- *     fanout-plan    list of companies we're about to sync
- *     progress       per-file download
- *     complete       per-company summary
- *     all-complete   aggregate summary after fanout
- *   stderr — diagnostic stream:
- *     error          per-file or per-company error
- *     auth-error     no valid token available (interactive login disabled)
- *
- * Why the split: error-class events go to stderr so the menubar's Sentry
- * breadcrumb pipeline picks them up automatically (see hq-sync
- * src-tauri/src/commands/sync.rs `ProcessEvent::Stderr` handler). The
- * single Sentry capture at runner-exit then ships one #hq-alerts issue
- * with the full per-file → company → exit error trail attached, instead
- * of requiring per-event capture calls in the menubar.
- *
- * Exit code:
- *   0 — event stream describes the outcome. The runner finished its protocol
- *       without any company throwing. Includes setup-needed, auth-error, and
- *       runs where every company completed OR cleanly returned `aborted: true`
- *       (a `--on-conflict abort` policy decision is not an error).
- *   1 — argv parse error or unrecoverable pre-sync failure.
- *   2 — at least one company threw a deterministic, non-transport failure
- *       mid-stream (e.g. mid-fanout 401, denied access, S3 5xx after retries).
- *       The all-complete event carries
- *       `partial: true` and per-company partial counts captured from
- *       `progress` events before the throw, so consumers parsing ndjson see
- *       what actually transferred. This is distinct from exit 0 with
- *       `partial: true` (clean conflict-aborts) — exit 2 is "something
- *       unexpected happened", which the Tauri menubar converts to a Sentry
- *       alert. Conflict-aborts intentionally do NOT alert.
- */
-
-import * as os from "os";
-import * as path from "path";
-import * as fs from "fs";
-import { randomUUID } from "node:crypto";
-import { fileURLToPath } from "url";
-import {
-  CognitoRefreshError,
-  getValidAccessToken,
-  invalidateCachedTokensByFingerprint,
-  loadCachedTokens,
-  VaultClient,
-  VaultAuthError,
-  type CognitoAuthConfig,
-  type CognitoTokens,
-  type VaultServiceConfig,
-  type Membership,
-  type EntityInfo,
-  type PendingInviteByEmail,
-  type MembershipSyncConfig,
-  type ExplicitGrant,
-} from "../index.js";
-import { pickCanonicalPersonEntity } from "../vault-client.js";
-import {
-  resolvePullScope,
-  readPinnedPrefixes,
-  SESSIONS_SCOPE_PREFIX,
-  type PullScope,
-} from "../sync/pull-scope.js";
-import {
-  PERSONAL_VAULT_EXCLUDED_TOP_LEVEL,
-  computePersonalVaultPaths,
-} from "../personal-vault.js";
-import { sync as defaultSync } from "../cli/sync.js";
-import type {
-  SyncOptions,
-  SyncResult,
-  SyncProgressEvent,
-} from "../cli/sync.js";
-import { share as defaultShare } from "../cli/share.js";
-import type { ShareOptions, ShareResult } from "../cli/share.js";
-import type { ConflictStrategy } from "../cli/conflict.js";
-import type { UploadAuthor } from "../s3.js";
-import {
-  setObjectIOFactory,
-  presignObjectIOFactory,
-  type ObjectIOFactory,
-  type PresignTransportClient,
-} from "../object-io.js";
-import { HQ_CLOUD_VERSION } from "../version.js";
-import { collectAndSendTelemetry } from "../telemetry.js";
-import { collectAndSendSkillTelemetry } from "../skill-telemetry.js";
-import { collectAndSendOutcomeTelemetry } from "../outcome-telemetry.js";
-import { emitCloudTelemetry } from "../telemetry-events.js";
-import { reindexAfterSync } from "../qmd-reindex.js";
-import type { ReindexOptions as QmdReindexOptions } from "../qmd-reindex.js";
-import { reindex as defaultReindex } from "../cli/reindex.js";
-import type { ReindexOptions, ReindexResult } from "../cli/reindex.js";
-import type {
-  TelemetryEventsBatch,
-  TelemetryEventsIngestResult,
-} from "../vault-client.js";
-import { pruneConflictIndex } from "../lib/conflict-index.js";
-import { materializeCodexAgents } from "../agent-codex-instructions.js";
-import { getOrCreateMachineId } from "../lib/machine-id.js";
-import {
-  isTransientNetworkError,
-  TRANSIENT_NETWORK_EXIT,
-} from "../lib/net-errors.js";
-import { PARTIAL_SYNC_EXIT } from "../lib/exit-codes.js";
-import { describeError } from "../lib/describe-error.js";
-import type {
-  Clock,
-  LocalDeleteSnapshot,
-  TreeChangeBatch,
-} from "../watcher.js";
-import type { PushReceiver, SyncEngineFn } from "../sync/push-receiver.js";
-import {
-  type EventSyncHandles,
-  type StartEventSyncOptions,
-} from "../sync/event-sync.js";
-import { migratePersonalVaultJournal } from "../journal.js";
-import {
-  createRunnerEmitter,
-  emitUncaughtRunnerError,
-} from "./sync-runner-events.js";
-import {
-  buildFanoutPlan,
-  emitFanoutPlan,
-  resolveMembershipsForRun,
-  resolveSkipCompanies,
-  type RunnerTarget,
-  type SetupNeededReason,
-} from "./sync-runner-planning.js";
-
-export { resolveSkipCompanies } from "./sync-runner-planning.js";
-import {
-  seedActiveCompany,
-  type SeedActiveCompanyOptions,
-  type SeedActiveCompanyResult,
-} from "../active-company.js";
-import {
-  reconcileCompanyManifest,
-  type ManifestReconcileOptions,
-  type ManifestReconcileResult,
-} from "../manifest-reconcile.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.
- *
- * - `pull`: download-only (legacy `hq sync` behaviour, and the default for
- *   back-compat with pre-5.1.11 callers of the runner).
- * - `push`: upload-only. Walks the company folder and sends every file whose
- *   local hash differs from the journal (skipUnchanged).
- * - `both`: push first, then pull. "Sync Now" in the menubar app targets this.
- *   Push runs first so the subsequent pull doesn't redownload files we were
- *   about to replace; if a company aborts on push conflict, pull is skipped
- *   for that company but the fanout continues.
- */
-export type Direction = "pull" | "push" | "both";
-
-// ---------------------------------------------------------------------------
-// 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
-// drift, the symptom is "runner talks to a different stage than hq sync"
-// — keep both files lined up.
-// ---------------------------------------------------------------------------
-
-const DEFAULT_COGNITO: CognitoAuthConfig = {
-  region: process.env.AWS_REGION ?? "us-east-1",
-  userPoolDomain: process.env.HQ_COGNITO_DOMAIN ?? "vault-indigo-hq-prod",
-  clientId: process.env.HQ_COGNITO_CLIENT_ID ?? "7acei2c8v870enheptb1j5foln",
-  port: process.env.HQ_COGNITO_CALLBACK_PORT
-    ? Number(process.env.HQ_COGNITO_CALLBACK_PORT)
-    : 8765,
-};
-
-const DEFAULT_VAULT_API_URL =
-  process.env.HQ_VAULT_API_URL ?? "https://hqapi.hq.computer";
-
-const DEFAULT_HQ_ROOT = path.join(os.homedir(), "hq");
-const DEFAULT_TELEMETRY_TIMEOUT_MS = 120_000;
-
-function resolveTelemetryTimeoutMs(override?: number): number {
-  if (override !== undefined && Number.isFinite(override) && override >= 0) {
-    return Math.trunc(override);
-  }
-  const raw = process.env.HQ_TELEMETRY_TIMEOUT_MS;
-  if (raw) {
-    const parsed = Number.parseInt(raw, 10);
-    if (Number.isFinite(parsed) && parsed >= 0) return parsed;
-  }
-  return DEFAULT_TELEMETRY_TIMEOUT_MS;
-}
-
-async function awaitTelemetryWithTimeout(
-  telemetry: Promise<void>,
-  timeoutMs: number,
-  onTimeout: () => void,
-): Promise<void> {
-  let timeout: ReturnType<typeof setTimeout> | undefined;
-  const timeoutPromise = new Promise<"timeout">((resolve) => {
-    timeout = setTimeout(() => resolve("timeout"), timeoutMs);
-    timeout.unref?.();
-  });
-  const result = await Promise.race([
-    telemetry.then(() => "done" as const),
-    timeoutPromise,
-  ]);
-  if (timeout) clearTimeout(timeout);
-  if (result === "timeout") onTimeout();
-}
-
-/**
- * Delete-propagation policy honored by the push leg of bidirectional sync.
- *
- * Default `"currency-gated"` in 5.25 — flipped from `"owned-only"` after
- * one machine (Indigo / corey) ran the 5.24 code path through real syncs
- * for a week without surfacing surprise behavior. Currency-gated does a
- * per-file ETag HEAD before propagating any local-delete to S3: if the
- * remote object's current ETag no longer matches the journal's last-
- * recorded one, the delete is refused and the next pull leg re-pulls the
- * file via the standard 3-way merge path. This is strictly safer than
- * `owned-only` (which propagates any local-delete the journal can prove
- * came from this device) — the only delete-class that changes behavior
- * is "deleted locally + modified remotely by another device", which
- * previously destroyed remote work and now becomes a pull-and-conflict.
- *
- * Env override `HQ_SYNC_DELETE_POLICY=owned-only|all|currency-gated` is
- * also the rollback knob — anyone surprised by 5.25's flip can revert
- * to `owned-only` without redeploying. `all` is the unsafe-mirror mode
- * previously used by the runner pre-5.20 — included only as an
- * emergency reconcile lever, not a recommended default.
- */
-export type DeletePropagationPolicy = "currency-gated" | "owned-only" | "all";
-
-export function resolveDeletePolicy(): DeletePropagationPolicy {
-  const env = process.env.HQ_SYNC_DELETE_POLICY;
-  if (env === "owned-only" || env === "all" || env === "currency-gated") {
-    return env;
-  }
-  return "currency-gated";
-}
-
-/**
- * Resolve whether to skip the personal target in a `--companies` fanout.
- *
- * Two inputs combine: the `--skip-personal` CLI flag (parsed into
- * `ParsedArgs.skipPersonal`) and the `HQ_SYNC_SKIP_PERSONAL` env var. Either
- * being truthy skips the personal target — flag wins on conflict (CLI
- * flag is the explicit-for-this-invocation knob, env is the persistent
- * default usually set by the menubar in the spawned child process).
- *
- * Env truthy values: `1`, `true`, `yes` (case-insensitive). Anything else
- * (including missing) is treated as falsy — same shape as classic
- * Unix opt-in env conventions; conservative to avoid surprising opt-outs.
- *
- * Use case: the menubar app exposes a "Sync personal vault" toggle in
- * Settings (default ON, matching the auto-provisioning UX). When the user
- * flips it off, the menubar spawns `hq sync` with this env set so the
- * fanout drops the personal target before walking the user's entire HQ
- * tree (a sync that would otherwise scan thousands of files, including
- * the new personal-vault default exclusions, just to do nothing useful).
- */
-export function resolveSkipPersonal(flag: boolean): boolean {
-  if (flag) return true;
-  const env = (process.env.HQ_SYNC_SKIP_PERSONAL ?? "").toLowerCase();
-  return env === "1" || env === "true" || env === "yes";
-}
-
-/**
- * Resolve the object-transport factory for this sync session.
- *
- * Company vaults (`cmp_*`) ALWAYS use the presigned-URL transport: the client
- * holds no raw AWS credentials (it fetches short-lived signed URLs) and every
- * read/write is authorized server-side per-file, so it never hits the 2048-char
- * STS session-policy ceiling that produced the HQ-59 lockout. The STS-direct-S3
- * (`S3SdkObjectIO`) path for company vaults is RETIRED — there is no env
- * override or rollback lever that can route a company vault back to direct S3.
- * (The former `HQ_SYNC_PRESIGN_TRANSPORT` kill-switch is gone with this change.)
- *
- * Personal vaults (`prs_*`) KEEP the direct-S3/STS path: the membership-gated
- * `list`/`presign` endpoints 403 for the membership-less vend-self model, and a
- * single-owner personal vault has no ACL-scale problem. That cmp_/prs_ split
- * lives inside {@link presignObjectIOFactory}.
- *
- * Returns `null` only when the client predates the presign methods (never in a
- * shipped build); the caller then resets to the SDK default factory.
- */
-export function selectObjectIOFactory(
-  client: Partial<PresignTransportClient>,
-): ObjectIOFactory | null {
-  if (
-    typeof client.presign === "function" &&
-    typeof client.listFiles === "function"
-  ) {
-    return presignObjectIOFactory(client as PresignTransportClient);
-  }
-  return null;
-}
-
-// Personal-vault scope (exclusion list + path computer) lives in
-// `../personal-vault.ts` so the `hq sync` CLI and this runner share the same
-// rules. Re-exported here for back-compat with any callers still importing
-// from sync-runner.js directly.
-export { PERSONAL_VAULT_EXCLUDED_TOP_LEVEL, computePersonalVaultPaths };
-
-// ---------------------------------------------------------------------------
-// Event protocol
-// ---------------------------------------------------------------------------
-
-/**
- * Every event the runner emits. Channel routing (stdout vs stderr) is
- * decided inside `runRunner`'s `emit` helper based on the event's `type`
- * — see the doc-block on the file header for the split.
- *
- * The `company` field is present on every event except `setup-needed` /
- * `auth-error` / `fanout-plan` / `all-complete` (which describe the whole
- * run) — consumers should treat its absence as "meta-event, not tied to a
- * specific company".
- */
-export type RunnerEvent =
-  | {
-      /**
-       * The run cannot proceed. `reason` and `pendingInviteCount` are additive
-       * and optional by design: a consumer that only reads `type` behaves
-       * exactly as before, while /setup and /hq-sync can tell the user WHY they
-       * look solo — most usefully, that an invite is still waiting.
-       */
-      type: "setup-needed";
-      reason?: SetupNeededReason;
-      pendingInviteCount?: number;
-    }
-  | { type: "auth-error"; message: string }
-  | {
-      /**
-       * The resolved fanout plan. Carries whole `RunnerTarget`s: the runtime
-       * payload has always been the plan entries verbatim, so the previous
-       * `{uid, slug, name?}` declaration understated the wire contract (it
-       * already omitted `bucketName`, `personalMode`, and `journalSlug`).
-       * Consumers deserialize leniently and ignore fields they do not know.
-       */
-      type: "fanout-plan";
-      companies: RunnerTarget[];
-    }
-  | ({
-      /**
-       * Stage-1 results for a single company's sync/share pass. Emitted once
-       * before any `progress` events for that company arrive — once for the
-       * pull phase (download counts) and once for the push phase (upload
-       * counts) when `--direction both`. Consumers (the menubar) sum the
-       * non-zero fields across all `plan` events seen for a fanout to render
-       * an accurate "X of Y files" denominator before transfers begin.
-       */
-      type: "plan";
-      company: string;
-    } & Omit<Extract<SyncProgressEvent, { type: "plan" }>, "type">)
-  | ({ type: "progress"; company: string } & Omit<Extract<SyncProgressEvent, { type: "progress" }>, "type">)
-  | ({ type: "error"; company?: string } & Omit<Extract<SyncProgressEvent, { type: "error" }>, "type">)
-  | {
-      /**
-       * A per-company transport failure that is retryable, not a deterministic
-       * sync error. This deliberately stays off the `error` channel: exit 2
-       * means a real partial sync failure, while this pass returns EX_TEMPFAIL
-       * (75) and is retried by the watch loop. Mirrors the non-error treatment
-       * of deliberate skip events.
-       */
-      type: "transient-network";
-      company: string;
-      path: "(company)";
-      message: string;
-    }
-  | ({ type: "conflict"; company: string } & Omit<Extract<SyncProgressEvent, { type: "conflict" }>, "type">)
-  | { type: "new-files"; company: string; files: Array<{ path: string; bytes: number; addedBy: string | null }> }
-  | { type: "scope-excluded"; company: string; count: number; samplePaths: string[] }
-  | ({ type: "scope-materialization-gap"; company: string } & Omit<
-      Extract<SyncProgressEvent, { type: "scope-materialization-gap" }>,
-      "type"
-    >)
-  | { type: "ignore-excluded"; company: string; count: number; totalExcluded: number; samplePaths: string[] }
-  | ({ type: "skip-invalid-scoped-key"; company: string } & Omit<
-      Extract<SyncProgressEvent, { type: "skip-invalid-scoped-key" }>,
-      "type"
-    >)
-  | ({ type: "skip-junk-key-spelling"; company: string } & Omit<
-      Extract<SyncProgressEvent, { type: "skip-junk-key-spelling" }>,
-      "type"
-    >)
-  | ({ type: "not-shipped"; company: string } & Omit<
-      Extract<SyncProgressEvent, { type: "not-shipped" }>,
-      "type"
-    >)
-  | ({
-      type: "complete";
-      company: string;
-      /**
-       * Upload counters. Always emitted (0 when the run was pull-only) so
-       * downstream consumers don't need to conditionally read the field.
-       */
-      filesUploaded: number;
-      bytesUploaded: number;
-      /**
-       * Push-side counters added in 5.25. Always emitted as numbers (0
-       * when no push leg ran). Tauri's `SyncCompleteEvent` carries them
-       * as Option<u32> for back-compat with <5.25 engines that don't
-       * include them; structural-typing-wise, the union just adds
-       * properties on top of `SyncResult`.
-       */
-      filesTombstoned: number;
-      filesRefusedStale: number;
-      /**
-       * Paths corresponding to `filesRefusedStale`, capped at 50 (mirrors
-       * `newFiles` cap). Surfaced on the `complete` event so operators
-       * can triage the recurring `filesRefusedStale: 205` signal that
-       * the 5.33.0 deep-test flagged as untriageable — the count alone
-       * is impossible to investigate after the per-file
-       * `delete-refused-stale-etag` events scroll off.
-       */
-      filesRefusedStalePaths: string[];
-      filesExcludedByPolicy: number;
-    } & SyncResult)
-  | {
-      type: "all-complete";
-      companiesAttempted: number;
-      filesDownloaded: number;
-      bytesDownloaded: number;
-      /** Always emitted; 0 when no push phase ran. */
-      filesUploaded: number;
-      bytesUploaded: number;
-      /**
-       * Conflict file paths aggregated across every company in the run.
-       * Always emitted; empty array when no conflicts were detected. Lets
-       * the menubar UI render a flat list without re-walking per-company
-       * `complete` events.
-      */
-      conflictPaths: Array<{ company: string; path: string; direction: "pull" | "push" }>;
-      errors: Array<{ company: string; message: string }>;
-      /**
-       * Retryable company-leg transport failures. Kept separate from `errors`
-       * so consumers can surface an incomplete pass without calling it a
-       * deterministic sync error. Always present for backward-compatible,
-       * additive protocol evolution.
-       */
-      transient: Array<{ company: string; message: string }>;
-      /**
-       * True when at least one company in the fanout did not complete cleanly
-       * — either it returned `aborted: true` (e.g. conflict-abort) or its sync
-       * function threw mid-stream (e.g. mid-fanout 401). When `partial: true`,
-       * the totals above include partial counts captured from `progress` events
-       * before the abort, NOT just companies that emitted a clean `complete`.
-       *
-       * Automated monitors should check this field — `errors.length > 0` alone
-       * isn't sufficient because a `aborted: true` return doesn't push to
-       * `errors` (it's a clean conflict-abort, not an exception).
-       */
-      partial: boolean;
-      /**
-       * Per-company breakdown of the fanout. Always present, one entry per
-       * planned company, in fanout order. Lets consumers reconcile per-company
-       * partial counts with the aggregate without re-walking `complete` /
-       * `error` event streams. The `status` field is the canonical signal:
-       * - "complete" — sync returned cleanly, `aborted: false`
-       * - "aborted"  — sync returned cleanly with `aborted: true` (conflict-abort)
-       * - "errored"  — sync threw mid-stream; counts are sourced from progress
-       *                events seen before the throw
-       * - "transient-network" — a retryable transport failure interrupted the
-       *                           leg; see `transient` for its diagnostic
-       */
-      companies: Array<{
-        company: string;
-        status: "complete" | "aborted" | "errored" | "transient-network";
-        filesDownloaded: number;
-        bytesDownloaded: number;
-        filesUploaded: number;
-        bytesUploaded: number;
-      }>;
-    }
-  | {
-      /**
-       * Emitted at most ONCE per fanout, AFTER `all-complete`, when the
-       * post-sync conflict-ledger prune leaves one or more PRESERVED conflict
-       * variants that a human still has to resolve (`kept > 0`). The prune
-       * self-heals the ledger (drops orphaned + byte-identical false-positive
-       * rows), but genuine divergences are conservatively KEPT — and pre-fix
-       * that residual set was silent, so the reporter of feedback_d2082110
-       * finished a full sync with "20 older preserved conflict entries" still
-       * on disk and no signal they were there. This event reconciles and
-       * surfaces the remaining count so the operator knows to run
-       * `/resolve-conflicts`. Ledger-global (not per-company — the index lives
-       * at the HQ root). Not emitted when the ledger is clean (`kept === 0`).
-       *
-       * `count` is the number of preserved conflict rows still awaiting
-       * resolution; `samplePaths` carries up to 10 original (non-mirror) paths
-       * for display.
-       */
-      type: "conflicts-remaining";
-      count: number;
-      samplePaths: string[];
-    };
-
-/**
- * The narrow VaultClient surface the runner actually uses. Declared here (not
- * `Pick<VaultClient, ...>`) because `Pick` preserves the *entire* `entity`
- * accessor object — but the runner only needs `entity.get`, and forcing test
- * stubs to also implement `findBySlug`/`create` would be dishonest about the
- * real dependency. Keep this interface in sync with the real VaultClient
- * method signatures (both return types come straight from the SDK).
- */
-export interface VaultClientSurface {
-  listMyMemberships: () => Promise<Membership[]>;
-  listMyPendingInvitesByEmail: () => Promise<PendingInviteByEmail[]>;
-  claimPendingInvitesByEmail: (personUid: string) => Promise<void>;
-  ensureMyPersonEntity: (hints: {
-    ownerSub: string;
-    displayName: string;
-  }) => Promise<EntityInfo>;
-  entity: {
-    get: (uid: string) => Promise<EntityInfo>;
-    listByType: (type: string) => Promise<EntityInfo[]>;
-  };
-  // US-005 scope resolution. Optional so older test stubs (and any
-  // VaultClientSurface impl that predates sync-config) still satisfy the
-  // interface; when absent, `resolvePullScope` degrades to `all`.
-  getMembershipSyncConfig?: (membershipId: string) => Promise<MembershipSyncConfig>;
-  listMyExplicitGrants?: (companyUid: string) => Promise<ExplicitGrant[]>;
-  postTelemetryEvents?: (
-    batch: TelemetryEventsBatch,
-    options?: { timeoutMs?: number },
-  ) => Promise<TelemetryEventsIngestResult>;
-}
-
-interface RunnerDiagnostic {
-  component: string;
-  event: string;
-  message: string;
-  err?: unknown;
-  context?: Record<string, unknown>;
-}
-
-type RunnerDiagnosticReporter = (diagnostic: RunnerDiagnostic) => void;
-
-function errorDetails(err: unknown): Record<string, unknown> {
-  const details: Record<string, unknown> = { message: describeError(err) };
-  if (err instanceof Error) {
-    if (err.name) details.name = err.name;
-    const code = (err as NodeJS.ErrnoException).code;
-    if (code) details.code = code;
-  }
-  return details;
-}
-
-function createRunnerDiagnosticReporter(
-  stderr: { write: (chunk: string) => boolean | void },
-): RunnerDiagnosticReporter {
-  return (diagnostic) => {
-    try {
-      const payload: Record<string, unknown> = {
-        type: "error",
-        diagnostic: true,
-        component: diagnostic.component,
-        event: diagnostic.event,
-        path: `(${diagnostic.component})`,
-        message:
-          diagnostic.err === undefined
-            ? diagnostic.message
-            : `${diagnostic.message}: ${describeError(diagnostic.err)}`,
-        ...(diagnostic.context ?? {}),
-      };
-      if (diagnostic.err !== undefined) {
-        payload.err = errorDetails(diagnostic.err);
-      }
-      stderr.write(`${JSON.stringify(payload)}\n`);
-    } catch {
-      /* diagnostics must never affect runner control flow */
-    }
-  };
-}
-
-// `resolvePullScope`, `readPinnedPrefixes`, and the `PullScope` type now live
-// in `../sync/pull-scope.ts` so the menubar runner and `hq sync pull|now`
-// (hq-cli) share ONE scope resolver — the drift between them was the root
-// cause of the all→shared scope-shrink wedge (DEV-1768). Re-exported here so
-// existing importers (and the runner test suite) keep their import path.
-export { resolvePullScope, readPinnedPrefixes, SESSIONS_SCOPE_PREFIX };
-export type { PullScope };
-
-/**
- * Backoff schedule (in ms) between attempts 2 and 3 of
- * `listMembershipsWithRetry`. Short on purpose — memberships is a single
- * API call gating the whole runner, and a transient blip (DNS hiccup,
- * idle ALB connection reset) usually clears in <50ms. If the network is
- * genuinely down, three attempts in <200ms total fail fast enough that
- * the tray can show its error banner before the user notices a delay.
- */
-const MEMBERSHIPS_RETRY_BACKOFFS_MS: readonly number[] = [50, 100];
-
-const REAUTH_MESSAGE =
-  "Your HQ session needs a quick refresh. Sign in again to keep sync moving.";
-
-/**
- * Internal-only result used between a watch pass and its owning loop. The
- * outer process still exits 0 (auth-required is a handled UX state), while
- * the loop stops instead of retrying a known-unusable session forever.
- */
-export const AUTH_REQUIRED_PASS_EXIT = 18;
-
-/**
- * Call `listMyMemberships()` with up to 3 attempts and a small linear
- * backoff between them. The single network call that drives every cloud
- * company target plus the personal-vault slot — a one-off network blip
- * shouldn't kill the whole sync run.
- *
- * Auth failures (VaultAuthError) bypass retry entirely: re-vending creds
- * is the caller's job, not retryable in-process. Re-throwing immediately
- * preserves the existing auth-error event semantics in the outer
- * try/catch.
- */
-async function listMembershipsWithRetry(
-  client: VaultClientSurface,
-): Promise<Membership[]> {
-  let lastErr: unknown;
-  for (let attempt = 0; attempt < 3; attempt++) {
-    if (attempt > 0) {
-      const delayMs = MEMBERSHIPS_RETRY_BACKOFFS_MS[attempt - 1] ?? 100;
-      await new Promise<void>((resolve) => setTimeout(resolve, delayMs));
-    }
-    try {
-      return await client.listMyMemberships();
-    } catch (err) {
-      if (err instanceof VaultAuthError) throw err;
-      lastErr = err;
-    }
-  }
-  throw lastErr;
-}
-
-/** Minimal shape of the claims we read off the Cognito idToken. */
-interface IdTokenClaims {
-  sub?: string;
-  email?: string;
-  name?: string;
-  given_name?: string;
-  family_name?: string;
-  /**
-   * Entity-bound machine-principal claims. A headless agent or Outpost
-   * authenticates with machine credentials; its idToken carries the machine's
-   * own entity binding here. The runner preserves those authenticated claims
-   * during planning. Agent claims additionally drive `--personal` target
-   * resolution to the agent's OWN entity (`custom:entityUid`, `agt_*`) instead
-   * of the person-only canonical pick.
-   */
-  "custom:entityType"?: string;
-  "custom:entityUid"?: string;
-}
-
-export interface RunnerDeps {
-  /** Where to write ndjson events. Defaults to `process.stdout`. */
-  stdout?: { write: (chunk: string) => boolean | void };
-  /** Where to write diagnostics. Defaults to `process.stderr`. */
-  stderr?: { write: (chunk: string) => boolean | void };
-  /** Resolve a valid access token. Defaults to `getValidAccessToken` non-interactive. */
-  getAccessToken?: () => Promise<string>;
-  /** Invalidate only the rejected token generation. Injectable for tests. */
-  clearSession?: (tokenFingerprint?: string) => void;
-  /**
-   * Read the caller's identity claims (sub/email/name) off the cached Cognito
-   * idToken. Defaults to decoding `loadCachedTokens().idToken`. Returns `null`
-   * when no cached tokens exist — the runner will then skip the claim-dance
-   * and fall through to the usual listMyMemberships path.
-   */
-  getIdTokenClaims?: () => IdTokenClaims | null;
-  /**
-   * Produce a VaultClient-like object. Defaults to `new VaultClient(config)`.
-   * Tests inject a stub here — the runner only calls the methods listed in
-   * `VaultClientSurface`.
-   */
-  createVaultClient?: (config: VaultServiceConfig) => VaultClientSurface;
-  /** Sync function. Defaults to `cli/sync.sync`. */
-  sync?: (options: SyncOptions) => Promise<SyncResult>;
-  /** Native post-fanout reindex function. Defaults to `cli/reindex.reindex`. */
-  reindex?: (options: ReindexOptions) => ReindexResult;
-  /** QMD post-sync reindex function. Defaults to `qmd-reindex.reindexAfterSync`. */
-  qmdReindex?: (
-    hqRoot: string,
-    options: QmdReindexOptions,
-  ) => ReturnType<typeof reindexAfterSync>;
-  /**
-   * Merge successfully pulled cloud companies into the local manifest after
-   * the complete fanout. Injectable so runner tests do not touch a developer's
-   * HQ root.
-   */
-  reconcileManifest?: (
-    options: ManifestReconcileOptions,
-  ) => Promise<ManifestReconcileResult>;
-  /** Internal test seam for `.hq/config.json` activeCompany seeding. */
-  seedActiveCompany?: (options: SeedActiveCompanyOptions) => SeedActiveCompanyResult;
-  /** Internal: set when runRunner is invoked under the per-root operation lock. */
-  operationLockAlreadyHeld?: boolean;
-  /** Internal watch-loop result override; one-shot callers keep exit 0. */
-  authRequiredExitCode?: number;
-  /** Internal watch-loop callback carrying uncapped per-path push outcomes. */
-  onPassResult?: (result: RunnerPassResult) => void;
-  /** Share function (push phase). Defaults to `cli/share.share`. */
-  share?: (options: ShareOptions) => Promise<ShareResult>;
-  /**
-   * Telemetry collector — runs just before the `all-complete` emit. Default
-   * implementation calls `collectAndSendTelemetry` from `../telemetry.js`
-   * using the real VaultClient; tests that inject `createVaultClient` are
-   * implicitly opted out (the default skips when the client isn't a real
-   * `VaultClient`). Tests that want to assert telemetry behavior should pass
-   * an explicit stub here.
-   */
-  collectTelemetry?: () => Promise<void>;
-  /** Maximum time to wait for pre-completion telemetry. Defaults to 120s. */
-  telemetryTimeoutMs?: number;
-}
-
-export interface RunnerPassResult {
-  pushPathResults: Array<{
-    relativePath: string;
-    status: "accepted" | "refused";
-    operation: "delete" | "tombstone";
-    reason?: string;
-  }>;
-  /** Company legs that threw before finishing their push/pull work. */
-  companyFailures?: Array<{ company: string; message: string }>;
-}
-
-export interface RunnerPassOutcome {
-  exitCode: number;
-  result?: RunnerPassResult;
-}
-
-// ---------------------------------------------------------------------------
-// JWT claim decoder — inlined to avoid pulling a dep just to read an idToken.
-// We do NOT verify the signature here — Cognito already did that when it
-// issued the token, and we only read the public claims (sub/email/name) to
-// drive the claim-dance + create the person entity. If the token is tampered
-// with, the downstream vault-service call will reject it (signature-verified
-// there) long before any claimed value causes harm.
-// ---------------------------------------------------------------------------
-
-function decodeJwtClaims(jwt: string): IdTokenClaims | null {
-  const parts = jwt.split(".");
-  if (parts.length !== 3) return null;
-  try {
-    const payload = parts[1].replace(/-/g, "+").replace(/_/g, "/");
-    const padded = payload + "=".repeat((4 - (payload.length % 4)) % 4);
-    const json = Buffer.from(padded, "base64").toString("utf-8");
-    return JSON.parse(json) as IdTokenClaims;
-  } catch {
-    return null;
-  }
-}
-
-function defaultGetIdTokenClaims(): IdTokenClaims | null {
-  const tokens: CognitoTokens | null = loadCachedTokens();
-  if (!tokens?.idToken) return null;
-  return decodeJwtClaims(tokens.idToken);
-}
-
-function isQmdIndexableContentPath(relPath: string): boolean {
-  const normalized = relPath.split(path.sep).join("/");
-  return (
-    /^companies\/[^/]+\/knowledge\/.+\.md$/i.test(normalized) ||
-    /^companies\/[^/]+\/projects\/.+\.(?:md|json)$/i.test(normalized) ||
-    /^personal\/knowledge\/.+\.md$/i.test(normalized)
-  );
-}
-
-/**
- * Best-effort: claim any email-keyed pending invites that were sent before
- * this user had a person entity. Mirrors the installer's vault-handoff flow.
- *
- * Silent on the happy path — only logs to stderr on soft failures (so a
- * transient network blip doesn't block the sync). Never throws: a caller who
- * can't list memberships despite an unclaimed invite is no worse off than the
- * pre-claim-dance behavior (which was to emit setup-needed).
- */
-async function runClaimDance(
-  client: VaultClientSurface,
-  claims: IdTokenClaims,
-  stderr: { write: (chunk: string) => boolean | void },
-  reportDiagnostic: RunnerDiagnosticReporter = () => undefined,
-): Promise<number> {
-  try {
-    const pending = await client.listMyPendingInvitesByEmail();
-    if (pending.length === 0) return 0;
-
-    const displayName =
-      claims.name ??
-      [claims.given_name, claims.family_name].filter(Boolean).join(" ") ??
-      claims.email ??
-      "";
-    const ownerSub = claims.sub ?? "";
-    if (!ownerSub || !displayName) {
-      reportDiagnostic({
-        component: "claim-dance",
-        event: "runner.claim_dance.skipped",
-        message: "skipping claim-dance — idToken missing sub/name",
-        context: { pendingInviteCount: pending.length },
-      });
-      // The invites are real and still pending; the caller must be able to say
-      // so even though we could not claim them.
-      return pending.length;
-    }
-
-    const person = await client.ensureMyPersonEntity({
-      ownerSub,
-      displayName,
-    });
-    await client.claimPendingInvitesByEmail(person.uid);
-    return pending.length;
-  } catch (err) {
-    // Non-throwing by contract: a claim-dance failure must never take down a
-    // sync. But it stops being invisible — a systematic failure here is exactly
-    // what makes a joiner look permanently solo.
-    reportDiagnostic({
-      component: "claim-dance",
-      event: "runner.claim_dance.skipped",
-      message: "claim-dance skipped",
-      err,
-      context: {},
-    });
-    return 0;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// argv parser — intentionally minimal (no commander/yargs dep)
-// ---------------------------------------------------------------------------
-
-interface ParsedArgs {
-  companies: boolean;
-  company?: string;
-  /**
-   * Personal-vault-only mode. Mutually exclusive with `--companies` and
-   * `--company`. Skips `listMyMemberships` (and therefore the claim-dance);
-   * builds a fanout plan containing ONLY the personal target. Designed as
-   * the runner-side entry point that replaces Rust's
-   * `personal.rs::run_personal_first_push` first-push walker — so the
-   * personal-vault scope (`computePersonalVaultPaths`) lives in exactly
-   * one place (this TS engine) and not duplicated across engines.
-   */
-  personal: boolean;
-  onConflict: ConflictStrategy;
-  hqRoot: string;
-  direction: Direction;
-  /** Auto-sync (Beta): keep the runner alive after the first pass. */
-  watch: boolean;
-  /** Auto-sync (Beta): ms between remote-pull passes. Required when watch=true. */
-  pollRemoteMs?: number;
-  /**
-   * Event-driven push (Phase 1). When set (and `--watch` is on), the runner
-   * starts a {@link TreeWatcher} alongside the poll loop and pushes a targeted
-   * company/subtree within the debounce window of a local edit — instead of
-   * waiting up to a full `--poll-remote-ms` cycle. Gated OFF by default; the
-   * menubar passes it only for `@getindigo.ai` identities (see PRD decision).
-   * No-op without `--watch` (the one-shot path has nothing to keep alive).
-   */
-  eventPush: boolean;
-  /**
-   * Drop the personal target from the fanout. Combined with the
-   * `HQ_SYNC_SKIP_PERSONAL` env var by `resolveSkipPersonal()` — either
-   * truthy disables personal sync for this run. No-op outside `--companies`
-   * mode (single-company runs never visit the personal target).
-   */
-  skipPersonal: boolean;
-  /** Repeatable company/personal-relative path scope for push-only passes. */
-  scopePaths: string[];
-  /**
-   * Internal watcher-only delete roots. Unlike `scopePaths`, these remain
-   * meaningful after the corresponding local file or directory is absent.
-   */
-  deleteScopePaths: string[];
-  /**
-   * Bounded wait (seconds) for the per-root operation lock when another op is
-   * already running. `0` → refuse immediately (pre-wait behavior); omitted →
-   * inherit `HQ_OP_LOCK_TIMEOUT` / infinite wait. Only meaningful on the
-   * one-shot path (the `--watch` runner is lock-exempt).
-   */
-  lockTimeoutSec?: number;
-}
-
-function parseArgs(argv: string[]): ParsedArgs | { error: string } {
-  let companies = false;
-  let company: string | undefined;
-  let personal = false;
-  let onConflict: ConflictStrategy = "abort";
-  let hqRoot = DEFAULT_HQ_ROOT;
-  let direction: Direction = "pull";
-  let watch = false;
-  let pollRemoteMs: number | undefined;
-  let skipPersonal = false;
-  const scopePaths: string[] = [];
-  const deleteScopePaths: string[] = [];
-  let eventPush = false;
-  let lockTimeoutSec: number | undefined;
-
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    switch (arg) {
-      case "--companies":
-        companies = true;
-        break;
-      case "--company":
-        company = argv[++i];
-        if (!company) return { error: "--company requires a value" };
-        break;
-      case "--personal":
-        // Personal-vault-only mode. Skips listMyMemberships + claim-dance
-        // entirely; builds a fanout plan containing only the personal target.
-        // Replaces Rust's personal.rs::run_personal_first_push walker —
-        // the personal-vault scope (computePersonalVaultPaths) is owned
-        // by this engine, not duplicated across Rust + TS.
-        personal = true;
-        break;
-      case "--on-conflict": {
-        const val = argv[++i];
-        if (val !== "abort" && val !== "overwrite" && val !== "keep") {
-          return {
-            error: `--on-conflict must be one of abort|overwrite|keep, got: ${val ?? "(missing)"}`,
-          };
-        }
-        onConflict = val;
-        break;
-      }
-      case "--direction": {
-        const val = argv[++i];
-        if (val !== "pull" && val !== "push" && val !== "both") {
-          return {
-            error: `--direction must be one of pull|push|both, got: ${val ?? "(missing)"}`,
-          };
-        }
-        direction = val;
-        break;
-      }
-      case "--hq-root":
-        hqRoot = argv[++i];
-        if (!hqRoot) return { error: "--hq-root requires a value" };
-        break;
-      case "--watch":
-        watch = true;
-        break;
-      case "--poll-remote-ms": {
-        const val = argv[++i];
-        if (!val) return { error: "--poll-remote-ms requires a value" };
-        const n = Number(val);
-        if (!Number.isInteger(n) || n <= 0) {
-          return {
-            error: `--poll-remote-ms must be a positive integer (ms), got: ${val}`,
-          };
-        }
-        pollRemoteMs = n;
-        break;
-      }
-      case "--json":
-        // Accepted but ignored — ndjson is the only output mode.
-        break;
-      case "--skip-personal":
-        // Drop the personal target from the fanout. No-op outside
-        // --companies mode. Combined with HQ_SYNC_SKIP_PERSONAL env via
-        // 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;
-      case "--scope-path": {
-        const val = argv[++i];
-        if (!val) return { error: "--scope-path requires a value" };
-        scopePaths.push(val);
-        break;
-      }
-      case "--delete-scope-path": {
-        const val = argv[++i];
-        if (!val) return { error: "--delete-scope-path requires a value" };
-        deleteScopePaths.push(val);
-        break;
-      }
-      case "--lock-timeout": {
-        const val = argv[++i];
-        if (!val) return { error: "--lock-timeout requires a value (seconds)" };
-        const n = Number(val);
-        if (!Number.isInteger(n) || n < 0) {
-          return {
-            error: `--lock-timeout must be a non-negative integer (seconds), got: ${val}`,
-          };
-        }
-        lockTimeoutSec = n;
-        break;
-      }
-      default:
-        return { error: `Unknown argument: ${arg}` };
-    }
-  }
-
-  if (companies && company) {
-    return { error: "Pass --companies OR --company <slug>, not both" };
-  }
-  if (personal && (companies || company)) {
-    return {
-      error: "--personal is mutually exclusive with --companies / --company",
-    };
-  }
-  if (personal && skipPersonal) {
-    return {
-      error: "--personal and --skip-personal are contradictory",
-    };
-  }
-  if (!companies && !company && !personal) {
-    return { error: "Pass --companies, --company <slug>, or --personal" };
-  }
-  if (pollRemoteMs !== undefined && !watch) {
-    return { error: "--poll-remote-ms requires --watch" };
-  }
-  if (eventPush && !watch) {
-    return { error: "--event-push requires --watch" };
-  }
-
-  return {
-    companies,
-    company,
-    personal,
-    onConflict,
-    hqRoot,
-    direction,
-    watch,
-    pollRemoteMs,
-    skipPersonal,
-    scopePaths,
-    deleteScopePaths,
-    eventPush,
-    lockTimeoutSec,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Telemetry default — closes over the runner's vault client. Skipped when
-// the caller injected a `createVaultClient` stub, because we have no
-// guarantee the stub implements `getTelemetryOptIn` / `postUsage`. The real
-// `VaultClient` from `../vault-client.js` always does. All errors are
-// swallowed — telemetry must never abort or delay sync.
-// ---------------------------------------------------------------------------
-
-export async function defaultCollectTelemetry(
-  client: VaultClientSurface,
-  clientIsStub: boolean,
-  hqRoot: string,
-  reportDiagnostic: RunnerDiagnosticReporter = () => undefined,
-  fallbackCompany?: string,
-): Promise<void> {
-  if (clientIsStub) return;
-
-  // Person-entity gate (the "onboarding gate" the telemetry call-site must
-  // sit behind). Both telemetry passes below resolve the caller's `personUid`
-  // SERVER-side from the JWT and reject with a 4xx when the caller has not yet
-  // been provisioned a person entity: `getTelemetryOptIn()` (the first call of
-  // each pass) hits `GET /v1/usage/opt-in`, which 404s `no-person-entity` for
-  // an unprovisioned caller, and the skill pass's `POST /v1/skill-invocations`
-  // does the same. hq-pro logs every such reject as a Sentry *warning*, so an
-  // unprovisioned-but-signed-in identity that runs telemetry on a loop — e.g.
-  // a machine/daemon/outpost identity, or a single-company sync that fabricates
-  // its membership and never runs the onboarding gate — emits a steady stream
-  // of benign `no-person-entity` warnings (Sentry HQ-4N). The reject itself is
-  // harmless (telemetry is best-effort and the response is swallowed), but the
-  // noise is not. Probe the caller's OWN person entity with the orphan-safe
-  // `entity.listByType("person")` — `GET /entity/by-type/person` returns `200`
-  // with an empty list for an unprovisioned caller (no reject, no warning),
-  // and a non-empty result is the EXACT predicate for "the server will resolve
-  // a personUid" (same caller-owned-person union the usage handler's
-  // `getEffectivePersonUid` uses). Skip both passes when there is none. The
-  // probe is the same canonical-person check the runner already uses to pick
-  // the personal-vault target. Fail OPEN: a thrown probe (transient/network)
-  // falls through to run telemetry as before, so a provisioned user's
-  // telemetry is never dropped by a flaky probe.
-  try {
-    const persons = await client.entity.listByType("person");
-    if (pickCanonicalPersonEntity(persons) === null) return;
-  } catch (err) {
-    reportDiagnostic({
-      component: "telemetry",
-      event: "runner.telemetry.person_probe_failed",
-      message: "telemetry person probe failed; continuing with telemetry",
-      err,
-      context: { hqRoot },
-    });
-    // Probe failed — preserve prior behavior and let telemetry run.
-  }
-
-  // machineId: hq-cloud owns provisioning via `<hqRoot>/.hq/machine-id`
-  // (see `src/lib/machine-id.ts`). The resolver migrates forward from
-  // any legacy `~/.hq/menubar.json` value on first call, then becomes
-  // self-sufficient. On a clean Linux outpost (no menubar app), a fresh
-  // UUID is generated + persisted, so this row is attributable rather
-  // than collapsing onto the legacy `"unknown"` sentinel.
-  //
-  // installerVersion: callers (the Tauri menubar) set this when spawning
-  // the runner so the historical `installerVersion` dimension on CloudWatch
-  // keeps reporting the menubar version, not the runner's package version.
-  // CLI callers can leave it unset.
-  //
-  // Resolved once and shared by both telemetry passes below. If identity
-  // resolution itself throws, skip telemetry entirely.
-  let machineId: string;
-  let installerVersion: string;
-  try {
-    machineId = getOrCreateMachineId(hqRoot);
-    installerVersion = process.env.HQ_INSTALLER_VERSION ?? "hq-cloud";
-  } catch (err) {
-    reportDiagnostic({
-      component: "telemetry",
-      event: "runner.telemetry.identity_failed",
-      message: "telemetry identity resolution failed; skipping telemetry",
-      err,
-      context: { hqRoot },
-    });
-    return;
-  }
-
-  try {
-    await collectAndSendTelemetry({
-      // The runtime guarantee here is that `clientIsStub === false` means
-      // `client` came from `new VaultClient(vaultConfig)` (see runRunner),
-      // which structurally satisfies `TelemetryClientSurface`.
-      client: client as unknown as Parameters<typeof collectAndSendTelemetry>[0]["client"],
-      machineId,
-      installerVersion,
-      // Resolve each event's cwd → owning company via <hqRoot>/companies/
-      // manifest.yaml and stamp companyUid (US-002). In explicit single-company
-      // runs, unmatched cwd values inherit that one scoped company; multi-company
-      // and personal runs keep them unattributed.
-      hqRoot,
-      fallbackCompany,
-      log: (message) =>
-        reportDiagnostic({
-          component: "telemetry",
-          event: "runner.telemetry.usage_nonfatal",
-          message,
-          context: { hqRoot },
-        }),
-    });
-  } catch (err) {
-    reportDiagnostic({
-      component: "telemetry",
-      event: "runner.telemetry.usage_failed",
-      message: "usage telemetry collector threw",
-      err,
-      context: { hqRoot },
-    });
-    // Fire-and-forget; nothing escapes the boundary.
-  }
-
-  // Skill-invocation telemetry runs as an independent pass (own cursor, own
-  // endpoint) so a failure here can never affect token telemetry above.
-  try {
-    await collectAndSendSkillTelemetry({
-      client: client as unknown as Parameters<typeof collectAndSendSkillTelemetry>[0]["client"],
-      machineId,
-      installerVersion,
-      // Scope skill capture to the HQ project — only invocations whose cwd is
-      // the HQ root are emitted; skill usage in unrelated repos is excluded.
-      hqRoot,
-      log: (message) =>
-        reportDiagnostic({
-          component: "telemetry",
-          event: "runner.telemetry.skill_nonfatal",
-          message,
-          context: { hqRoot },
-        }),
-    });
-  } catch (err) {
-    reportDiagnostic({
-      component: "telemetry",
-      event: "runner.telemetry.skill_failed",
-      message: "skill telemetry collector threw",
-      err,
-      context: { hqRoot },
-    });
-    // Fire-and-forget; nothing escapes the boundary.
-  }
-
-  // Outcome telemetry runs as an independent pass (own cursor, own endpoint,
-  // outcome-leaderboard US-004) so a failure here can never affect token or
-  // skill telemetry above. It diffs prd.json story `passes` + board.json project
-  // `status` transitions against a local cursor and POSTs story-completed /
-  // project-shipped events. No machineId/installerVersion — the /v1/outcome-events
-  // contract accepts only { events }.
-  try {
-    await collectAndSendOutcomeTelemetry({
-      client: client as unknown as Parameters<typeof collectAndSendOutcomeTelemetry>[0]["client"],
-      // Scan <hqRoot>/companies/* for prd.json/board.json and resolve each
-      // project's owning company via <hqRoot>/companies/manifest.yaml.
-      hqRoot,
-      log: (message) =>
-        reportDiagnostic({
-          component: "telemetry",
-          event: "runner.telemetry.outcome_nonfatal",
-          message,
-          context: { hqRoot },
-        }),
-    });
-  } catch (err) {
-    reportDiagnostic({
-      component: "telemetry",
-      event: "runner.telemetry.outcome_failed",
-      message: "outcome telemetry collector threw",
-      err,
-      context: { hqRoot },
-    });
-    // Fire-and-forget; nothing escapes the boundary.
-  }
-}
-
-// ---------------------------------------------------------------------------
-// runRunner — testable entrypoint
-// ---------------------------------------------------------------------------
-
-export async function runRunner(
-  argv: string[],
-  deps: RunnerDeps = {},
-): Promise<number> {
-  const stdout = deps.stdout ?? process.stdout;
-  const stderr = deps.stderr ?? process.stderr;
-  const reportDiagnostic = createRunnerDiagnosticReporter(stderr);
-
-  // ---- emit ---------------------------------------------------------------
-  // Error-class events go to stderr; everything else to stdout.
-  //
-  // Why split: the AppBar Sync menubar (Tauri + Rust) feeds runner stderr
-  // into Sentry as breadcrumbs and captures one Sentry event when the
-  // runner exits non-zero. Routing `error` / `auth-error` events through
-  // stderr makes them part of that breadcrumb trail automatically — the
-  // menubar doesn't need a per-event capture call, and operators get the
-  // full context (per-file errors → company error → exit) in a single
-  // Sentry issue alerted to #hq-alerts.
-  //
-  // Non-error events (progress, complete, transient-network, fanout-plan,
-  // all-complete, setup-needed) stay on stdout. They're the protocol stream the menubar
-  // parses for UI updates; mixing them with error events on the same
-  // channel was the original design (single ndjson stream, simpler to
-  // tee), but error context belongs in the diagnostic channel.
-  //
-  // Backward compat: older menubar releases (pre-PR-#34) parse only
-  // stdout for ndjson; with this change they will NOT receive error
-  // 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 emit = createRunnerEmitter({ stdout, stderr });
-
-  // ---- argv -------------------------------------------------------------
-  const parsed = parseArgs(argv);
-  if ("error" in parsed) {
-    stderr.write(`hq-sync-runner: ${parsed.error}\n`);
-    return 1;
-  }
-
-  // ---- auth -------------------------------------------------------------
-  // Resolve the access token up-front to surface auth-error early (before any
-  // protocol events). Long-running multi-company syncs can outlast Cognito's
-  // 60-min access token TTL, so the vaultConfig captures a *getter* — every
-  // vault request resolves the latest token via getValidAccessToken, which
-  // re-reads `~/.hq/cognito-tokens.json` and refreshes on demand. Without
-  // this, a captured string goes stale mid-fanout (e.g. personal sync runs
-  // last → STS expires after 13 min → refreshEntityContext → fetchEntity →
-  // 401 against API Gateway's JWT authorizer because the captured token
-  // expired while the menubar was happily rotating the on-disk token).
-  const getAccessToken =
-    deps.getAccessToken ??
-    (() => getValidAccessToken(DEFAULT_COGNITO, { interactive: false }));
-  const clearSession =
-    deps.clearSession ?? invalidateCachedTokensByFingerprint;
-  let initialAuthToken: string;
-  try {
-    initialAuthToken = await getAccessToken();
-  } catch (err) {
-    if (
-      (err instanceof CognitoRefreshError && !err.requiresReauth) ||
-      isTransientNetworkError(err)
-    ) {
-      emit({
-        type: "error",
-        path: "(auth)",
-        message: err instanceof Error ? err.message : String(err),
-      });
-      return TRANSIENT_NETWORK_EXIT;
-    }
-    emit({
-      type: "auth-error",
-      message: REAUTH_MESSAGE,
-    });
-    return deps.authRequiredExitCode ?? 0;
-  }
-
-  // ---- vault client -----------------------------------------------------
-  // Stamp clientInfo so every vault request (incl. /sts/vend) carries
-  // x-hq-client-name=hq-sync + x-hq-client-version=<hq-cloud version>. The
-  // company-vend min-version gate (HQ-59, hq-pro) uses this to recognize a
-  // compliant (>= 6.11.6) sync-runner and NOT force-upgrade it — the
-  // belt-and-suspenders companion to skipping the cmp_ vend on the presign
-  // path. Version is the hq-cloud package version (what the gate compares to
-  // its floor), not the desktop app version.
-  const vaultConfig: VaultServiceConfig = {
-    apiUrl: DEFAULT_VAULT_API_URL,
-    authToken: getAccessToken,
-    region: DEFAULT_COGNITO.region,
-    clientInfo: { name: "hq-sync", version: HQ_CLOUD_VERSION },
-  };
-  const client =
-    deps.createVaultClient?.(vaultConfig) ?? new VaultClient(vaultConfig);
-
-  // ---- resolve identity claims -----------------------------------------
-  // Read the cached idToken claims once. Two consumers downstream:
-  //   1. The claim-dance (only fires in `--companies` mode for setup-needed
-  //      invitees).
-  //   2. The S3 upload author (every share() call stamps `Metadata['created-by']`
-  //      with `claims.email` so the hq-console vault UI's CREATED BY column
-  //      attributes the file to the syncing user).
-  // Resolved here (not inside `parsed.companies`) so single-company runs also
-  // get author attribution. `null` is fine — share() simply omits the metadata.
-  const getClaims = deps.getIdTokenClaims ?? defaultGetIdTokenClaims;
-  // A machine-principal token is minted immediately above and is an ID token.
-  // Make its entity binding authoritative for this run: a stale human token
-  // cache can otherwise make an authenticated machine look like a person
-  // during fanout planning. Human callers still retain the cache as their
-  // primary claims source because their bearer is normally an access token
-  // without the full ID-token profile.
-  const authenticatedClaims = decodeJwtClaims(initialAuthToken);
-  const authenticatedMachinePrincipalClaims =
-    authenticatedClaims &&
-    (authenticatedClaims["custom:entityType"] === "agent" ||
-      authenticatedClaims["custom:entityType"] === "outpost") &&
-    typeof authenticatedClaims["custom:entityUid"] === "string"
-      ? authenticatedClaims
-      : null;
-  const claims =
-    authenticatedMachinePrincipalClaims ?? getClaims() ?? authenticatedClaims;
-  const uploadAuthor: UploadAuthor | undefined =
-    claims?.sub && claims?.email
-      ? { userSub: claims.sub, email: claims.email }
-      : undefined;
-  const telemetrySessionId = `sync_${randomUUID()}`;
-  void emitCloudTelemetry(
-    client,
-    {
-      eventName: "sync_runner_session_started",
-      source: "sync-runner",
-      sessionId: telemetrySessionId,
-      properties: {
-        direction: parsed.direction,
-        targetMode: parsed.personal
-          ? "personal"
-          : parsed.company
-            ? "single_company"
-            : "companies",
-        watchState: parsed.watch ? "enabled" : "disabled",
-        eventPushState: parsed.eventPush ? "enabled" : "disabled",
-        scopePathCount: parsed.scopePaths?.length ?? 0,
-      },
-    },
-    {
-      claims,
-      log: (message) =>
-        reportDiagnostic({
-          component: "telemetry-events",
-          event: "runner.telemetry_events.nonfatal",
-          message,
-          context: { source: "sync-runner" },
-        }),
-    },
-  );
-
-  const emitRunnerTerminalTelemetry = (properties: {
-    status: "completed" | "partial" | "failed";
-    attemptedCount?: number;
-    companyCount?: number;
-    errorCount?: number;
-    filesDownloaded?: number;
-    bytesDownloaded?: number;
-    filesUploaded?: number;
-    bytesUploaded?: number;
-  }): void => {
-    void emitCloudTelemetry(
-      client,
-      {
-        eventName: "sync_runner_completed",
-        source: "sync-runner",
-        sessionId: telemetrySessionId,
-        properties,
-      },
-      {
-        claims,
-        log: (message) =>
-          reportDiagnostic({
-            component: "telemetry-events",
-            event: "runner.telemetry_events.nonfatal",
-            message,
-            context: { source: "sync-runner" },
-          }),
-      },
-    );
-  };
-
-  // ---- transport selection (presigned-URL for cmp_, direct-S3/STS for prs_) -
-  // Company vaults ALWAYS use the presigned-URL transport now (HQ-59): the
-  // STS-direct-S3 path for cmp_ is retired — no env override routes a company
-  // vault back to direct S3. Personal vaults keep direct-S3 inside the factory
-  // (the cmp_/prs_ split lives in presignObjectIOFactory). selectObjectIOFactory
-  // runs ONCE here — every s3.ts call in this session's fanout resolves through
-  // the installed factory. Setting it unconditionally (even to null, which the
-  // default S3 SDK factory backs for a pre-presign client) keeps the choice
-  // deterministic if a prior run mutated module state.
-  const presignCapable = client as Partial<PresignTransportClient>;
-  const objectIOFactory = selectObjectIOFactory(presignCapable);
-  setObjectIOFactory(objectIOFactory);
-  // HQ-59 vend-skip: when company vaults run over the presign transport (the
-  // shipped case — selectObjectIOFactory only returns null for a pre-presign
-  // client), tell resolveEntityContext to SKIP `POST /sts/vend` for cmp_
-  // contexts. Two reasons, both load-bearing: (1) the presign transport never
-  // reads STS creds, so the vend is dead weight; (2) a compliant sync-runner
-  // must not call the company vend route at all — its presence is the
-  // pre-6.11.6 signal the hq-pro min-version gate denies on. Gated on the SAME
-  // value that picks the transport, so the vend-skip and the transport can
-  // never diverge. If the factory is null (S3 SDK fallback), cmp_ keeps vending
-  // because S3SdkObjectIO needs the creds. Personal vaults always vend self.
-  vaultConfig.companyVaultUsesPresign = objectIOFactory !== null;
-
-  // ---- resolve targets --------------------------------------------------
-  let memberships: Pick<Membership, "companyUid">[];
-  try {
-    const resolution = await resolveMembershipsForRun({
-      personal: parsed.personal,
-      companies: parsed.companies,
-      company: parsed.company,
-      client,
-      claims,
-      stderr,
-      runClaimDance: (client, claims, stderr) =>
-        runClaimDance(client, claims, stderr, reportDiagnostic),
-      listMemberships: listMembershipsWithRetry,
-    });
-    if (resolution.status === "setup-needed") {
-      emit({
-        type: "setup-needed",
-        reason: resolution.reason,
-        ...(resolution.pendingInviteCount === undefined
-          ? {}
-          : { pendingInviteCount: resolution.pendingInviteCount }),
-      });
-      return 0;
-    }
-    memberships = resolution.memberships;
-  } catch (err) {
-    if (err instanceof VaultAuthError) {
-      clearSession(err.tokenFingerprint);
-      emit({
-        type: "auth-error",
-        message: REAUTH_MESSAGE,
-      });
-      return deps.authRequiredExitCode ?? 0;
-    }
-    // Surface the failure as an error event for observability either way.
-    emit({
-      type: "error",
-      message: err instanceof Error ? err.message : String(err),
-      path: "(discovery)",
-    });
-    emitRunnerTerminalTelemetry({ status: "failed" });
-    // A transient network failure (offline, DNS blip, vault API briefly
-    // unreachable) is NOT a crash — it self-heals on the next poll. Return the
-    // retryable exit code so the watch loop stays alive instead of exiting and
-    // being reported as "watcher exited unexpectedly (code=Some(1))" for every
-    // blip (HQ-SYNC-1W). A one-shot run still exits non-zero. Any other failure
-    // is treated as a hard error (exit 1), as before.
-    return isTransientNetworkError(err) ? TRANSIENT_NETWORK_EXIT : 1;
-  }
-
-  let targetPlan: Awaited<ReturnType<typeof buildFanoutPlan>>;
-  try {
-    targetPlan = await buildFanoutPlan({
-      memberships,
-      companies: parsed.companies,
-      personal: parsed.personal,
-      skipPersonal: parsed.skipPersonal,
-      client,
-      claims,
-      resolveSkipPersonal,
-      skipCompanies: resolveSkipCompanies(),
-    });
-  } catch (err) {
-    if (err instanceof VaultAuthError) {
-      clearSession(err.tokenFingerprint);
-      emit({ type: "auth-error", message: REAUTH_MESSAGE });
-      return deps.authRequiredExitCode ?? 0;
-    }
-    emit({
-      type: "error",
-      message: err instanceof Error ? err.message : String(err),
-      path: "(discovery)",
-    });
-    emitRunnerTerminalTelemetry({ status: "failed" });
-    return isTransientNetworkError(err) ? TRANSIENT_NETWORK_EXIT : 1;
-  }
-  if (targetPlan.status === "setup-needed") {
-    emit({ type: "setup-needed", reason: targetPlan.reason });
-    return 0;
-  }
-  const plan = targetPlan.plan;
-  const deferredUnresolved = targetPlan.deferredUnresolved;
-
-  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
-  // when the new journal already exists or the legacy one is absent, and
-  // harmless even when the personal-vault slot is not in the plan.
-  migratePersonalVaultJournal();
-
-  // ---- fanout -----------------------------------------------------------
-  const syncFn = deps.sync ?? defaultSync;
-  const shareFn = deps.share ?? defaultShare;
-  let fanout: Awaited<ReturnType<typeof executeCompanyFanout>>;
-  try {
-    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,
-      scopePaths: parsed.scopePaths,
-      deleteScopePaths: parsed.deleteScopePaths,
-      telemetryClient: client,
-      telemetryClaims: claims,
-      telemetrySessionId,
-    });
-  } catch (err) {
-    if (err instanceof VaultAuthError) {
-      clearSession(err.tokenFingerprint);
-      emit({ type: "auth-error", message: REAUTH_MESSAGE });
-      return deps.authRequiredExitCode ?? 0;
-    }
-    throw err;
-  }
-  const { errors, transientCompanies, allConflicts, meaningfulOutcomeCount } = fanout;
-  deps.onPassResult?.({
-    pushPathResults: fanout.pushPathResults,
-    companyFailures: fanout.companyFailures,
-  });
-  const rollup = rollupAllComplete(plan, fanout.stateByCompany);
-
-  // The personal-vault target runs last and can pull an older copy of the
-  // manifest. Reconcile only after the entire pull fanout has settled so the
-  // successfully materialized cloud directories restore their own entries.
-  //
-  // `--companies` only. A single-company run (`--company <slug>`) and a
-  // `--personal` run both see just one leg of the fanout, so neither has the
-  // full picture the manifest is reconciled against; treating a partial view as
-  // authoritative is how entries get lost. A push-only pass materializes
-  // nothing new locally, so it has nothing to reconcile either.
-  if (parsed.companies && parsed.direction !== "push") {
-    const completedCompanySlugs = new Set(
-      Array.from(fanout.stateByCompany.entries())
-        .filter(([, state]) => state.status === "complete")
-        .map(([slug]) => slug),
-    );
-    // The personal vault is never a manifest entry. The reconciler filters it
-    // too, but that is its own internal invariant — excluding it here means
-    // the personal target is never even handed across the seam.
-    const companyTargets = plan.filter(
-      (target) => target.personalMode !== true && target.slug !== "personal",
-    );
-    try {
-      const result = await (deps.reconcileManifest ?? reconcileCompanyManifest)({
-        hqRoot: parsed.hqRoot,
-        targets: companyTargets,
-        completedCompanySlugs,
-        reportDiagnostic: (diagnostic) =>
-          reportDiagnostic({ component: "manifest-reconcile", ...diagnostic }),
-      });
-      // Only on an actual write. A steady-state sync stays silent, so an
-      // unexpected diagnostic rate is itself the signal that skip-if-unchanged
-      // has regressed.
-      if (result.written) {
-        reportDiagnostic({
-          component: "manifest-reconcile",
-          event: "manifest-reconciled",
-          message: "restored company entries in companies/manifest.yaml",
-          context: { added: result.added, updated: result.updated },
-        });
-      }
-    } catch (err) {
-      reportDiagnostic({
-        component: "manifest-reconcile",
-        event: "runner.manifest_reconcile.failed",
-        message: "post-fanout manifest reconciliation failed",
-        err,
-        context: { hqRoot: parsed.hqRoot },
-      });
-    }
-
-    // A joiner whose manifest entry was just restored still has nothing telling
-    // HQ which company is current. Seed it only when the answer cannot be wrong
-    // — deliberately its own try, so a manifest failure does not also cost the
-    // user their routing.
-    try {
-      const localCompanySlugs = companyTargets
-        .map((target) => target.slug)
-        .filter((slug) => completedCompanySlugs.has(slug));
-      const seeded = (deps.seedActiveCompany ?? seedActiveCompany)({
-        hqRoot: parsed.hqRoot,
-        companySlugs: localCompanySlugs,
-        reportDiagnostic: (diagnostic) =>
-          reportDiagnostic({ component: "active-company", ...diagnostic }),
-      });
-      if (seeded.written) {
-        reportDiagnostic({
-          component: "active-company",
-          event: "active-company-seeded",
-          message: "seeded activeCompany in .hq/config.json",
-          context: { activeCompany: seeded.activeCompany },
-        });
-      }
-    } catch (err) {
-      reportDiagnostic({
-        component: "active-company",
-        event: "runner.active_company.failed",
-        message: "seeding activeCompany failed",
-        err,
-        context: { hqRoot: parsed.hqRoot },
-      });
-    }
-  }
-
-  if (rollup.needsReindex) {
-    try {
-      const reindexOptions = {
-        repoRoot: parsed.hqRoot,
-        ...(deps.operationLockAlreadyHeld === true ? { skipLock: true } : {}),
-      };
-      const reindexResult = (deps.reindex ?? defaultReindex)(reindexOptions);
-      void emitCloudTelemetry(
-        client,
-        {
-          eventName: "reindex_run",
-          source: "sync-runner",
-          sessionId: telemetrySessionId,
-          properties: {
-            result: reindexResult.status === 0 ? "completed" : "failed",
-            statusCode: reindexResult.status,
-            changedCount: rollup.changedPaths.length,
-            lockResult:
-              deps.operationLockAlreadyHeld === true ? "skipped" : "attempted",
-          },
-        },
-        {
-          claims,
-          log: (message) =>
-            reportDiagnostic({
-              component: "telemetry-events",
-              event: "runner.telemetry_events.nonfatal",
-              message,
-              context: { source: "sync-runner" },
-            }),
-        },
-      );
-    } catch (err) {
-      reportDiagnostic({
-        component: "native-reindex",
-        event: "runner.native_reindex.failed",
-        message: "post-fanout native reindex failed",
-        err,
-        context: { hqRoot: parsed.hqRoot },
-      });
-      void emitCloudTelemetry(
-        client,
-        {
-          eventName: "reindex_run",
-          source: "sync-runner",
-          sessionId: telemetrySessionId,
-          properties: {
-            result: "threw",
-            changedCount: rollup.changedPaths.length,
-            lockResult:
-              deps.operationLockAlreadyHeld === true ? "skipped" : "attempted",
-          },
-        },
-        {
-          claims,
-          log: (message) =>
-            reportDiagnostic({
-              component: "telemetry-events",
-              event: "runner.telemetry_events.nonfatal",
-              message,
-              context: { source: "sync-runner" },
-            }),
-        },
-      );
-    }
-  }
-
-  // Fire telemetry collector before the all-complete emit so the cursor at
-  // `~/.hq/telemetry-cursor.json` is consistent with what the menubar sees.
-  await awaitTelemetryWithTimeout(
-    emitTelemetry({
-      collectTelemetry: deps.collectTelemetry,
-      defaultCollectTelemetry: () =>
-        defaultCollectTelemetry(
-          client,
-          deps.createVaultClient !== undefined,
-          parsed.hqRoot,
-          reportDiagnostic,
-          parsed.company,
-        ),
-      onError: (err) =>
-        reportDiagnostic({
-          component: "telemetry",
-          event: "runner.telemetry.collector_failed",
-          message: "telemetry collector failed",
-          err,
-          context: { hqRoot: parsed.hqRoot },
-        }),
-    }),
-    resolveTelemetryTimeoutMs(deps.telemetryTimeoutMs),
-    () =>
-      reportDiagnostic({
-        component: "telemetry",
-        event: "runner.telemetry.timeout",
-        message: "telemetry collector timed out; continuing sync completion",
-        context: { hqRoot: parsed.hqRoot },
-      }),
-  );
-
-  emit({
-    type: "all-complete",
-    companiesAttempted: plan.length,
-    filesDownloaded: rollup.totalDownloaded,
-    bytesDownloaded: rollup.totalDownloadedBytes,
-    filesUploaded: rollup.totalUploaded,
-    bytesUploaded: rollup.totalUploadedBytes,
-    conflictPaths: allConflicts,
-    errors,
-    transient: transientCompanies,
-    partial: rollup.partial,
-    companies: rollup.companies,
-  });
-  if (
-    rollup.partial ||
-    errors.length > 0 ||
-    meaningfulOutcomeCount > 0
-  ) {
-    emitRunnerTerminalTelemetry({
-      status: rollup.partial || errors.length > 0 ? "partial" : "completed",
-      attemptedCount: plan.length,
-      companyCount: rollup.companies.length,
-      errorCount: errors.length,
-      filesDownloaded: rollup.totalDownloaded,
-      bytesDownloaded: rollup.totalDownloadedBytes,
-      filesUploaded: rollup.totalUploaded,
-      bytesUploaded: rollup.totalUploadedBytes,
-    });
-  }
-
-  // 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
-  // step that never affects the exit code. Only when files were actually
-  // 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.
-  const qmdChangedPaths = rollup.changedPaths.filter(isQmdIndexableContentPath);
-  if (qmdChangedPaths.length > 0 && process.env.HQ_QMD_REINDEX_ON_SYNC !== "0") {
-    try {
-      const qmdResult = (deps.qmdReindex ?? reindexAfterSync)(parsed.hqRoot, {
-        changedPaths: qmdChangedPaths,
-        forceCollectionRefresh: true,
-        log: ({ event, message, err, context }) =>
-          reportDiagnostic({
-            component: "qmd-reindex",
-            event,
-            message,
-            err,
-            context: { hqRoot: parsed.hqRoot, ...(context ?? {}) },
-          }),
-      });
-      void emitCloudTelemetry(
-        client,
-        {
-          eventName: "qmd_reindex_run",
-          source: "sync-runner",
-          sessionId: telemetrySessionId,
-          properties: {
-            result: "completed",
-            changedCount: qmdChangedPaths.length,
-            qmdState: qmdResult.qmdAvailable ? "available" : "unavailable",
-            collectionsAddedCount: qmdResult.collectionsAdded.length,
-            pathDriftDetectedCount: qmdResult.pathDriftDetected?.length ?? 0,
-            collectionsRepairedCount: qmdResult.collectionsRepaired?.length ?? 0,
-            updateState: qmdResult.updated ? "updated" : "unchanged",
-            embedState: qmdResult.embedded ? "embedded" : "not_embedded",
-            dirtyState: qmdResult.pendingDirty ? "pending_dirty" : "clean",
-            lockBusy: qmdResult.lockBusy === true ? 1 : 0,
-            timedOut: qmdResult.timedOut === true ? 1 : 0,
-            corruptionQuarantined: qmdResult.corruptionQuarantined === true ? 1 : 0,
-            corruptionQuarantineFailed: qmdResult.corruptionQuarantineFailed === true ? 1 : 0,
-          },
-        },
-        {
-          claims,
-          log: (message) =>
-            reportDiagnostic({
-              component: "telemetry-events",
-              event: "runner.telemetry_events.nonfatal",
-              message,
-              context: { source: "sync-runner" },
-            }),
-        },
-      );
-    } catch (err) {
-      reportDiagnostic({
-        component: "qmd-reindex",
-        event: "runner.qmd_reindex.failed",
-        message: "post-sync qmd reindex threw",
-        err,
-        context: { hqRoot: parsed.hqRoot },
-      });
-      // Defensive: reindexAfterSync already swallows internally.
-      void emitCloudTelemetry(
-        client,
-        {
-          eventName: "qmd_reindex_run",
-          source: "sync-runner",
-          sessionId: telemetrySessionId,
-          properties: {
-            result: "threw",
-            changedCount: qmdChangedPaths.length,
-          },
-        },
-        {
-          claims,
-          log: (message) =>
-            reportDiagnostic({
-              component: "telemetry-events",
-              event: "runner.telemetry_events.nonfatal",
-              message,
-              context: { source: "sync-runner" },
-            }),
-        },
-      );
-    }
-  }
-
-  // Post-sync conflict-ledger prune — also a best-effort tail step (runs AFTER
-  // `all-complete`, never touches the exit code). The producers only append a
-  // conflict row after proving real divergence, but the ledger has no other
-  // self-healing path: rows for byte-identical false positives (legacy or
-  // since-reverted) and orphaned `.conflict-*` mirrors otherwise linger
-  // forever and make `.hq-conflicts/index.json` over-report. One GC pass per
-  // run keeps it converged. Idempotent and cheap on a clean ledger (a no-row
-  // index returns immediately and never rewrites the file). Opt-out via
-  // HQ_CONFLICT_PRUNE_ON_SYNC=0.
-  if (process.env.HQ_CONFLICT_PRUNE_ON_SYNC !== "0") {
-    try {
-      const pruneResult = pruneConflictIndex(parsed.hqRoot);
-      // Reconcile + surface the residual preserved conflict variants a human
-      // still has to resolve. Pre-fix this set was silent — the reporter of
-      // feedback_d2082110 finished a full sync with 20 preserved conflict
-      // entries still on disk and no signal. Emitting after the prune means the
-      // count reflects the self-healed (orphan/false-positive-dropped) ledger,
-      // never the inflated raw one. Ledger-global; silent on a clean ledger.
-      if (pruneResult.kept > 0) {
-        emit({
-          type: "conflicts-remaining",
-          count: pruneResult.kept,
-          samplePaths: pruneResult.keptSamplePaths,
-        });
-      }
-    } catch (err) {
-      reportDiagnostic({
-        component: "conflict-index",
-        event: "runner.conflict_index.prune_failed",
-        message: "post-sync conflict index prune failed",
-        err,
-        context: { hqRoot: parsed.hqRoot },
-      });
-      // Defensive: a prune failure must never affect the sync outcome.
-    }
-  }
-
-  // Post-sync agent codex-instructions materialization — best-effort tail step
-  // (runs AFTER `all-complete`, never affects the exit code). For an AGENT box
-  // ONLY (`custom:entityType === "agent"`), project the synced personal/ agent
-  // overlay (agents-profile.md + agent-capabilities/*.md) into the codex GLOBAL
-  // instruction file ~/.codex/AGENTS.md, which `codex exec` natively merges on
-  // every run. This is the codex mirror of Claude's ~/.claude/CLAUDE.md:
-  // DURABLE (outside the hq-root, so `hq rescue` never touches it) and
-  // fleet-SCALABLE (every box runs @latest each cycle). A human running
-  // `hq sync` (person identity) never triggers it. Opt-out: set
-  // HQ_AGENT_CODEX_MATERIALIZE=0. The write is idempotent and never destructive
-  // (skips when the overlay is empty), and never throws (mirrors the qmd /
-  // conflict-prune tail steps above).
-  if (
-    claims?.["custom:entityType"] === "agent" &&
-    process.env.HQ_AGENT_CODEX_MATERIALIZE !== "0"
-  ) {
-    try {
-      materializeCodexAgents({
-        hqRoot: parsed.hqRoot,
-        log: ({ event, message, err, context }) =>
-          reportDiagnostic({
-            component: "agent-codex-instructions",
-            event,
-            message,
-            err,
-            context: { hqRoot: parsed.hqRoot, ...(context ?? {}) },
-          }),
-      });
-    } catch (err) {
-      reportDiagnostic({
-        component: "agent-codex-instructions",
-        event: "runner.agent_codex_instructions.failed",
-        message: "post-sync agent codex-instructions materialization threw",
-        err,
-        context: { hqRoot: parsed.hqRoot },
-      });
-      // Defensive: materializeCodexAgents already swallows internally.
-    }
-  }
-
-  // Exit PARTIAL_SYNC_EXIT (2) only when something actually threw
-  // (`errors.length > 0`). A clean conflict-abort sets `partial: true` in the
-  // JSON but exits 0 — the Tauri menubar's non-zero-exit Sentry capture would
-  // otherwise fire for normal user-policy outcomes. Consumers that want to
-  // flag any non-clean outcome (clean-abort + thrown-error) read `partial`
-  // from the JSON. The watch loop stays alive on this code (see exit-codes.ts).
-  //
-  // deferredUnresolved: a slug denylist was active but entity discovery blipped
-  // for one or more memberships we could not prove were paused. Fail closed on
-  // the plan (they were omitted) and return TRANSIENT so watch scoped drain
-  // does not publish without a successful upload pass.
-  if (errors.length > 0) return PARTIAL_SYNC_EXIT;
-  if (transientCompanies.length > 0 || deferredUnresolved > 0) {
-    return TRANSIENT_NETWORK_EXIT;
-  }
-  return 0;
-}
-
-// ---------------------------------------------------------------------------
-// Entrypoint — only runs when invoked directly, not when imported for tests
-// ---------------------------------------------------------------------------
-
-// Detect whether this module is the entry point. The obvious check
-// (`import.meta.url === file://${argv[1]}`) breaks for every real-world
-// install shape: npm-link'd binaries, global installs via Homebrew, and
-// pnpm's `node_modules/.bin` shims all leave `process.argv[1]` pointing
-// at a symlink named `hq-sync-runner` (no `.js` suffix) while
-// `import.meta.url` always resolves to the underlying `sync-runner.js`.
-//
-// Resolve both sides through realpath before comparing — that's the only
-// way to handle all symlink layouts without false negatives. If realpath
-// fails (argv[1] gone, permissions), fall through to `false` so we
-// don't run twice when imported as a library.
-const isDirectInvocation = (() => {
-  if (!process.argv[1]) return false;
-  try {
-    const modulePath = fs.realpathSync(fileURLToPath(import.meta.url));
-    const argvPath = fs.realpathSync(process.argv[1]);
-    return modulePath === argvPath;
-  } catch {
-    return false;
-  }
-})();
-
-/**
- * Test/event-driven seam (US-001).
- *
- * `runRunnerWithLoop` performs an unbounded, monotonic-cadence loop in
- * production. The initial pass is immediate; subsequent deadlines advance
- * from their prior deadline rather than pass completion. Watcher and receiver
- * signals interrupt the wait but still use the same guarded pass queue. To
- * test it deterministically, both waiting and monotonic time are injectable.
- *
- * 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>;
-  /**
-   * Monotonic milliseconds source for cadence deadlines. Defaults to
-   * `performance.now()`; tests inject it to prove missed-deadline behavior
-   * without depending on wall-clock time.
-   */
-  monotonicNow?: () => number;
-  /**
-   * 1-minute whole-box load average source for the adaptive remote-poll
-   * backoff (used only when `--poll-remote-ms` is omitted). Defaults to
-   * `os.loadavg()[0]`. Tests inject a fixed sample to assert the interval
-   * scales with load without depending on the host's real load.
-   */
-  sampleLoadAvg?: () => number;
-  /**
-   * 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 | RunnerPassOutcome>;
-  /** Stage-0 backup retention backstop: a dry-run only, never a sync-tick action. */
-  runBackupPrune?: (hqRoot: string) => Promise<void>;
-  /**
-   * 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;
-    captureLocalDeleteSnapshots: (
-      relativePath: string,
-      kind: "unlink" | "unlinkDir",
-    ) => LocalDeleteSnapshot[];
-  }) => 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;
-  /**
-   * Phase 3 (US-017/US-018/US-019): factory for the event-driven publish +
-   * pull wiring, consulted only when `--event-push` is on AND the rollout
-   * gate ({@link resolveEventSync}) passes for the signed-in account.
-   * Defaults to the real {@link defaultStartEventSync}. Tests inject a stub
-   * to assert gate behavior without network/AWS.
-   */
-  startEventSync?: (
-    opts: StartEventSyncOptions,
-  ) => Promise<EventSyncHandles | null>;
-  /**
-   * Identity-claims source for the Phase 3 rollout gate (the loop has no
-   * RunnerDeps; mirror of RunnerDeps.getIdTokenClaims). Defaults to reading
-   * the cached Cognito idToken.
-   */
-  getIdTokenClaims?: () => IdTokenClaims | null;
-  /**
-   * Access-token source for the Phase 3 vault API calls (publish transport +
-   * subscribe). Defaults to {@link getValidAccessToken} non-interactive.
-   */
-  getAccessToken?: () => Promise<string>;
-}
-
-/**
- * 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, batch?: TreeChangeBatch) => void,
-  ): () => void;
-  start(): void;
-  stop(): void;
-  dispose(): void;
-}
-
-export async function runRunnerWithLoop(
-  argv: string[],
-  deps: RunnerLoopDeps = {},
-): Promise<number> {
-  const parsed = parseArgs(argv);
-  const runtime = {
-    runPassWithOperationLockAlreadyHeld: async (passArgv: string[]) => {
-      let result: RunnerPassResult | undefined;
-      const exitCode = await runRunner(passArgv, {
-        operationLockAlreadyHeld: true,
-        authRequiredExitCode: AUTH_REQUIRED_PASS_EXIT,
-        onPassResult: (passResult) => {
-          result = passResult;
-        },
-      });
-      return { exitCode, ...(result ? { result } : {}) };
-    },
-    authRequiredPassExit: AUTH_REQUIRED_PASS_EXIT,
-    defaultGetIdTokenClaims,
-    defaultGetAccessToken: () =>
-      getValidAccessToken(DEFAULT_COGNITO, { interactive: false }),
-    apiUrl: DEFAULT_VAULT_API_URL,
-    region: DEFAULT_COGNITO.region,
-  };
-
-  if (!argv.includes("--watch")) {
-    if ("error" in parsed) return runRunner(argv);
-    return runOneShotWithOperationLock(argv, parsed, deps, runtime);
-  }
-
-  if ("error" in parsed) return runRunner(argv);
-  return runWatchLoop(argv, parsed, deps, runtime);
-}
-
-if (isDirectInvocation) {
-  runRunnerWithLoop(process.argv.slice(2))
-    .then((code) => process.exit(code))
-    .catch((err) => {
-      // A top-level rejection means the runner died before (or instead of)
-      // emitting its protocol stream. Emit a CLASSIFIED `error` event first so
-      // the menubar runs it through `is_alertable_error` and suppresses the
-      // benign cases, instead of treating every uncaught exit as an unexplained
-      // "silent death" crash (HQ-SYNC-WEB-6).
-      emitUncaughtRunnerError(err, {
-        stdout: process.stdout,
-        stderr: process.stderr,
-      });
-      process.exit(1);
-    });
-}