@indigoai-us/hq-cli 5.77.14 → 5.78.0

package/src/commands/cloud.ts

@@ -1,2130 +0,0 @@
-/**
- * `hq sync` commands — push/pull files between the local HQ tree and the
- * company's S3 vault bucket.
- *
- * VLT-5 model: each command resolves a Cognito access token, asks
- * vault-service for the company's bucket + STS-vended credentials, and
- * runs the operation. No daemon, no init step (handled by `hq onboard`),
- * no long-lived background process — every invocation is self-contained.
- *
- * Subcommands:
- *   hq sync push [paths...]   — broadcast local file(s) to the vault
- *   hq sync pull              — pull all permitted files from the vault
- *   hq sync status            — show local journal summary
- */
-
-import { Command } from "commander";
-import chalk from "chalk";
-import * as fs from "fs";
-import * as path from "path";
-
-import {
-  share,
-  sync,
-  getStateDir,
-  listJournals,
-  loadCachedTokens,
-  VaultClient,
-  computePersonalVaultPaths,
-  PERSONAL_VAULT_JOURNAL_SLUG,
-  resolvePullScope,
-  type ConflictStrategy,
-  type EntityContext,
-  type MembershipSyncConfig,
-  type SyncMode,
-  type PullScope,
-  type ExplicitGrant,
-  type SyncProgressEvent,
-  type UploadAuthor,
-} from "@indigoai-us/hq-cloud";
-
-import {
-  DEFAULT_HQ_ROOT,
-  ensureCognitoToken,
-  buildVaultConfig,
-} from "../utils/cognito-session.js";
-import {
-  emitNarrowHint,
-  isStrictRefusal,
-  resolveBannerLevel,
-  type BannerLevel,
-} from "../lib/narrow-hint-banner.js";
-
-/**
- * Build a loud, human-readable warning when a push dropped files because
- * they fell outside the caller's granted write scope. Returns null when
- * nothing was scope-excluded. Keeping this pure makes the "never silently
- * succeed when files were dropped" guarantee unit-testable.
- */
-export function scopeExcludedWarning(count: number): string | null {
-  if (count <= 0) return null;
-  return (
-    `⚠ ${count} file(s) were NOT uploaded — they fall outside the ` +
-    `prefixes you have write access to (company-wide or direct grants). ` +
-    `They were skipped, not synced. Re-run with --json to list them, or ` +
-    `ask an admin to grant you write on those paths.`
-  );
-}
-
-/**
- * Resolve the `propagateDeletePolicy` for share() calls.
- *
- * Mirrors `@indigoai-us/hq-cloud`'s `bin/sync-runner.js` `resolveDeletePolicy`
- * — the same function the AppBar HQ Sync menubar uses — so the CLI and the
- * menubar agree on the policy by default. Inlined here (rather than
- * deep-imported from `dist/bin/sync-runner.js`) to avoid coupling to a
- * non-public subpath.
- *
- * Default is `"currency-gated"` (etag-verified safe delete). Override via
- * the `HQ_SYNC_DELETE_POLICY` env var: `owned-only` (legacy direction-of-
- * origin filter, multi-user safe but stranded down-stream litter on
- * personal vaults until hq-cloud 6.0.1's prs_ override), `currency-gated`
- * (the menubar default), or `all` (emergency-reconcile, no safety gates).
- *
- * Prior to this helper, the CLI passed nothing → share() fell through to
- * its own `"owned-only"` default, leaving CLI users on a stricter (and
- * sometimes wrong, on personal vault) policy than menubar users for
- * months. See `workspace/reports/owned-only-delete-policy-purpose-debug.md`.
- */
-function resolveDeletePolicy(): "owned-only" | "currency-gated" | "all" {
-  const env = process.env.HQ_SYNC_DELETE_POLICY;
-  if (env === "owned-only" || env === "all" || env === "currency-gated") {
-    return env;
-  }
-  return "currency-gated";
-}
-
-interface CommonSyncOptions {
-  hqRoot: string;
-  company?: string;
-  lockTimeout?: string;
-}
-
-const DEFAULT_SYNC_LOCK_TIMEOUT_SECONDS = 300;
-
-/**
- * Bound foreground waits for a watcher/manual sync that currently owns the
- * per-root operation lock. The cloud engine reads this environment value on
- * every lock acquisition. A command-line value wins; otherwise preserve a
- * valid explicit caller environment value and supply a finite CLI default.
- */
-export function configureSyncLockTimeout(raw: string | undefined): void {
-  const value = raw ?? process.env.HQ_OP_LOCK_TIMEOUT ?? String(DEFAULT_SYNC_LOCK_TIMEOUT_SECONDS);
-  const seconds = Number(value);
-  if (!Number.isInteger(seconds) || seconds < 0) {
-    throw new Error("--lock-timeout must be a non-negative integer number of seconds");
-  }
-  process.env.HQ_OP_LOCK_TIMEOUT = String(seconds);
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// `hq sync pull --all` orchestrator
-//
-// Mirrors the fanout that `hq-sync-runner --companies --direction pull` does
-// in the menubar app: list every membership, append the canonical person
-// entity, sync each target into <hq-root>. Extracted as a pure function with
-// injectable deps so cloud.pull-all.test.ts can drive it without network.
-// ─────────────────────────────────────────────────────────────────────────────
-
-export interface PullAllVaultClient {
-  listMyMemberships(): Promise<
-    Array<{ companyUid: string; membershipKey?: string }>
-  >;
-  listPersonEntities(): Promise<
-    Array<{
-      uid: string;
-      type: string;
-      slug: string;
-      bucketName?: string;
-      createdAt: string;
-    }>
-  >;
-  getEntity(uid: string): Promise<{ slug?: string; name?: string } | null>;
-  /**
-   * US-011: optional — when present, `pullAll` calls it once per
-   * membership to surface the narrow-hint banner for all-mode owners.
-   * Absent on legacy adapters (push-all et al.) where the banner is not
-   * applicable.
-   */
-  getMembershipSyncConfig?: (
-    membershipId: string,
-  ) => Promise<MembershipSyncConfig>;
-  /**
-   * Caller's explicit grants for a company — consumed by `resolvePullScope`
-   * to build a `shared`-mode prefix set. Optional so legacy adapters degrade
-   * to `all` (the safe direction).
-   */
-  listMyExplicitGrants?: (companyUid: string) => Promise<ExplicitGrant[]>;
-}
-
-export interface SyncCallOptions {
-  company: string;
-  hqRoot: string;
-  onConflict?: ConflictStrategy;
-  personalMode?: boolean;
-  journalSlug?: string;
-  /**
-   * Effective pull scope (DEV-1768). When set, `sync()` materializes only the
-   * in-scope keys and scope-shrinks the rest — instead of defaulting to
-   * `syncMode: "all"` and stamping an all-mode PullRecord that wedges the next
-   * menubar sync. Resolved per-company by the shared `resolvePullScope`.
-   */
-  syncMode?: SyncMode;
-  prefixSet?: string[];
-  /**
-   * Company-relative prefixes the pull must NOT materialize even when the
-   * caller's STS scope is wide enough to read them (sessions-exclusion /
-   * company-work-corpus). Derived by `resolvePullScope` in the hq-cloud release
-   * carrying the sessions/ pull-exclusion, forwarded to `sync()` here so the CLI
-   * honors the same "session transcripts never sync DOWN" invariant the
-   * background sync engine enforces. A company OWNER can read `sessions/` keys,
-   * so without this the CLI would bulk-download everyone's full-content session
-   * transcripts to local disk. Undefined/empty ⇒ nothing excluded (legacy).
-   */
-  excludePrefixes?: string[];
-  /** Honor a `--force-scope-shrink` on a foreground pull (dirty files kept). */
-  forceScopeShrink?: boolean;
-}
-
-export interface SyncCallResult {
-  filesDownloaded: number;
-  bytesDownloaded: number;
-  filesSkipped: number;
-  conflicts: number;
-  conflictPaths: string[];
-  aborted: boolean;
-}
-
-export interface PullAllDeps {
-  vaultClient: PullAllVaultClient;
-  sync: (options: SyncCallOptions) => Promise<SyncCallResult>;
-  /**
-   * Resolve a company's effective pull scope (DEV-1768). Injected so `pullAll`
-   * stays pure/testable; the real entry point wires it to the shared
-   * `resolvePullScope` over a live `VaultClient`. When absent, the per-company
-   * leg falls back to `all` (legacy behavior) — only the real path injects it.
-   */
-  resolveScope?: (companyUid: string, slug: string) => Promise<PullScope>;
-}
-
-export interface PullAllOptions {
-  hqRoot: string;
-  onConflict?: ConflictStrategy;
-  /**
-   * US-011: banner level for the narrow-hint nudge. Defaults to `'hint'`
-   * — see `resolveBannerLevel` for the env-driven override. The
-   * `'strict'` level causes `pullAll` to refuse to sync any membership
-   * still on `syncMode: 'all'` unless `modeAllOverride` is true.
-   *
-   * TODO(hq-core-staging release N+2): default flips to 'warning'.
-   * TODO(hq-core-staging release N+3): default flips to 'strict'.
-   */
-  narrowHintLevel?: BannerLevel;
-  /**
-   * US-011: when `true`, strict-mode does NOT refuse all-mode
-   * memberships — the operator has explicitly opted into keeping the
-   * legacy behavior for this run via `--mode-all`.
-   */
-  modeAllOverride?: boolean;
-  /**
-   * When `true`, skip the canonical-person-entity leg entirely — the
-   * fanout only visits the caller's company memberships. Mirrors the
-   * `--skip-personal` flag and `HQ_SYNC_SKIP_PERSONAL` env var that
-   * `@indigoai-us/hq-cloud`'s `sync-runner` exposes in `--companies`
-   * mode (see hq-cloud 5.25.0 `resolveSkipPersonal`). Surfaced on the
-   * CLI as `hq sync pull --all --no-personal` so the AppBar HQ Sync
-   * menubar toggle (and CLI users opting out one-off) can drop the
-   * personal vault from the run without touching the rest of the plan.
-   */
-  skipPersonal?: boolean;
-  /**
-   * Forward `--force-scope-shrink` to each company leg: when a scope shrink
-   * would un-track locally-modified files, proceed anyway (dirty files KEPT on
-   * disk, only un-tracked). Makes the foreground "block" advice followable.
-   */
-  forceScopeShrink?: boolean;
-}
-
-export interface PullAllRow {
-  slug: string;
-  result?: SyncCallResult;
-  error?: string;
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// `hq sync push --all` orchestrator — symmetric with pullAll.
-//
-// Plan: every membership → company target (paths = the company's local
-// subtree); plus the canonical person entity → personal target (paths =
-// computePersonalVaultPaths(hqRoot)). Each target calls share() with
-// skipUnchanged + propagateDeletes so re-runs are cheap and on-disk deletes
-// propagate to the vault — same defaults the menubar runner uses.
-// ─────────────────────────────────────────────────────────────────────────────
-
-export interface ShareCallOptions {
-  company: string;
-  hqRoot: string;
-  paths: string[];
-  onConflict?: ConflictStrategy;
-  personalMode?: boolean;
-  journalSlug?: string;
-  message?: string;
-  skipUnchanged?: boolean;
-  propagateDeletes?: boolean;
-  propagateDeletePolicy?: "owned-only" | "currency-gated" | "all";
-}
-
-export interface ShareCallResult {
-  filesUploaded: number;
-  bytesUploaded: number;
-  filesSkipped: number;
-  filesDeleted: number;
-  filesExcludedByScope: number;
-  conflictPaths: string[];
-  aborted: boolean;
-}
-
-export interface PushAllDeps {
-  vaultClient: PullAllVaultClient;
-  share: (options: ShareCallOptions) => Promise<ShareCallResult>;
-}
-
-export interface PushAllOptions {
-  hqRoot: string;
-  onConflict?: ConflictStrategy;
-  message?: string;
-  /**
-   * When `true`, skip the canonical-person-entity leg entirely — the
-   * fanout only visits the caller's company memberships. Symmetric with
-   * `PullAllOptions.skipPersonal`; surfaced on the CLI as
-   * `hq sync push --all --no-personal`.
-   */
-  skipPersonal?: boolean;
-}
-
-export interface PushAllRow {
-  slug: string;
-  result?: ShareCallResult;
-  error?: string;
-}
-
-export interface PushAllResult {
-  attempted: number;
-  filesUploaded: number;
-  bytesUploaded: number;
-  filesDeleted: number;
-  filesExcludedByScope: number;
-  errors: Array<{ company: string; message: string }>;
-  perCompany: PushAllRow[];
-}
-
-export interface PullAllResult {
-  attempted: number;
-  filesDownloaded: number;
-  bytesDownloaded: number;
-  conflicts: number;
-  errors: Array<{ company: string; message: string }>;
-  perCompany: PullAllRow[];
-}
-
-interface PlanEntry {
-  slug: string;
-  syncOptions: SyncCallOptions;
-  /** US-011: tracked so we can resolve sync-config + emit the narrow hint. */
-  companyUid?: string;
-  membershipKey?: string;
-}
-
-// Oldest-first by createdAt, ties broken by uid lexicographic — matches
-// `pickCanonicalPersonEntity` in @indigoai-us/hq-cloud so the CLI lands on
-// the same person bucket that `hq-sync-runner` picks.
-function pickCanonicalPerson<
-  E extends { uid: string; type: string; createdAt: string },
->(persons: E[]): E | null {
-  const onlyPersons = persons.filter((e) => e.type === "person");
-  if (onlyPersons.length === 0) return null;
-  return [...onlyPersons].sort((a, b) => {
-    if (a.createdAt !== b.createdAt) return a.createdAt < b.createdAt ? -1 : 1;
-    return a.uid < b.uid ? -1 : 1;
-  })[0];
-}
-
-/**
- * Read the sessions-exclusion prefix set off a resolved {@link PullScope}.
- *
- * `resolvePullScope` in hq-cloud derives the sessions/ pull-exclusion and
- * derives `excludePrefixes` (e.g. `["sessions/"]`) so a company OWNER — whose STS
- * scope is wide enough to read `sessions/` keys — does not bulk-download
- * everyone's full-content session transcripts to local disk, upholding the
- * "session transcripts never sync DOWN" invariant hq-cloud enforces for the
- * background engine. Keep the small runtime shape check even though PullScope
- * now declares the field: it protects the CLI when an older external resolver
- * implementation is injected by tests or downstream callers.
- */
-function readScopeExcludePrefixes(
-  scope: PullScope | undefined,
-): string[] | undefined {
-  const raw: unknown = scope?.excludePrefixes;
-  if (!Array.isArray(raw)) return undefined;
-  const prefixes = raw.filter(
-    (p): p is string => typeof p === "string" && p.length > 0,
-  );
-  return prefixes.length > 0 ? prefixes : undefined;
-}
-
-export async function pullAll(
-  options: PullAllOptions,
-  deps: PullAllDeps,
-): Promise<PullAllResult> {
-  const memberships = await deps.vaultClient.listMyMemberships();
-  const persons = await deps.vaultClient.listPersonEntities();
-
-  const narrowHintLevel: BannerLevel = options.narrowHintLevel ?? "hint";
-  const getSyncConfig = deps.vaultClient.getMembershipSyncConfig;
-
-  const plan: PlanEntry[] = [];
-  for (const m of memberships) {
-    let slug = m.companyUid;
-    try {
-      const info = await deps.vaultClient.getEntity(m.companyUid);
-      if (info?.slug) slug = info.slug;
-    } catch {
-      // Best-effort — keep UID as the row label rather than aborting the run.
-    }
-    plan.push({
-      slug,
-      companyUid: m.companyUid,
-      ...(m.membershipKey ? { membershipKey: m.membershipKey } : {}),
-      syncOptions: {
-        company: m.companyUid,
-        hqRoot: options.hqRoot,
-        ...(options.onConflict ? { onConflict: options.onConflict } : {}),
-      },
-    });
-  }
-
-  const personal = options.skipPersonal ? null : pickCanonicalPerson(persons);
-  if (personal) {
-    // Canonical slug, NOT the literal "personal": that legacy slug is the
-    // companies/personal company's journal. hq-sync-runner moved the vault
-    // slot to PERSONAL_VAULT_JOURNAL_SLUG; hq-cli journaling the same vault
-    // under the old slug split the bookkeeping across two files — every CLI
-    // sync re-flagged the menubar's already-synced files as conflicts.
-    plan.push({
-      slug: "personal",
-      syncOptions: {
-        company: personal.uid,
-        hqRoot: options.hqRoot,
-        personalMode: true,
-        journalSlug: PERSONAL_VAULT_JOURNAL_SLUG,
-        ...(options.onConflict ? { onConflict: options.onConflict } : {}),
-      },
-    });
-  }
-
-  const result: PullAllResult = {
-    attempted: 0,
-    filesDownloaded: 0,
-    bytesDownloaded: 0,
-    conflicts: 0,
-    errors: [],
-    perCompany: [],
-  };
-
-  for (const entry of plan) {
-    result.attempted += 1;
-
-    // Resolve the membership's effective sync scope. DEV-1768: this must drive
-    // the actual pull (mode + prefixSet), not just the narrow-hint banner — the
-    // old code resolved the mode for the banner and then called sync() with NO
-    // scope, so every CLI pull ran `syncMode: "all"` and stamped an all-mode
-    // PullRecord that wedged the next menubar sync (all→shared scope-shrink).
-    // The shared `resolvePullScope` (via deps.resolveScope) degrades to `all`
-    // on any failure, so a transient blip never narrows scope.
-    let resolvedMode: MembershipSyncConfig["syncMode"] | undefined;
-    if (entry.companyUid && deps.resolveScope) {
-      try {
-        const scope = await deps.resolveScope(entry.companyUid, entry.slug);
-        resolvedMode = scope.syncMode;
-        entry.syncOptions.syncMode = scope.syncMode;
-        if (scope.prefixSet !== undefined) {
-          entry.syncOptions.prefixSet = scope.prefixSet;
-        }
-        // Sessions-exclusion: thread the resolver's excludePrefixes into the
-        // pull so a wide-STS OWNER never bulk-downloads session transcripts.
-        const excludePrefixes = readScopeExcludePrefixes(scope);
-        if (excludePrefixes) {
-          entry.syncOptions.excludePrefixes = excludePrefixes;
-        }
-      } catch {
-        resolvedMode = undefined;
-      }
-    } else if (entry.membershipKey && getSyncConfig) {
-      // Fallback when no scope resolver is injected (legacy/test paths):
-      // banner-only mode resolution, preserving the pre-DEV-1768 behavior.
-      try {
-        const cfg = await getSyncConfig(entry.membershipKey);
-        resolvedMode = cfg.syncMode;
-      } catch {
-        resolvedMode = undefined;
-      }
-    }
-    if (options.forceScopeShrink && entry.companyUid) {
-      entry.syncOptions.forceScopeShrink = true;
-    }
-
-    if (
-      resolvedMode === "all" &&
-      isStrictRefusal(resolvedMode, narrowHintLevel) &&
-      !options.modeAllOverride &&
-      entry.companyUid
-    ) {
-      // Emit the strict-level banner once, then mark the leg as errored
-      // without invoking sync(). The operator either narrows the
-      // membership (`hq sync narrow --apply`) or passes `--mode-all` to
-      // opt back in.
-      emitNarrowHint({
-        companyUid: entry.companyUid,
-        syncMode: resolvedMode,
-        level: narrowHintLevel,
-      });
-      const message =
-        "Refusing to pull all-mode membership in strict mode. " +
-        "Run `hq sync narrow --apply` to migrate, or re-run with --mode-all.";
-      result.errors.push({ company: entry.slug, message });
-      result.perCompany.push({ slug: entry.slug, error: message });
-      continue;
-    }
-
-    try {
-      const r = await deps.sync(entry.syncOptions);
-      result.filesDownloaded += r.filesDownloaded;
-      result.bytesDownloaded += r.bytesDownloaded;
-      result.conflicts += r.conflicts;
-      result.perCompany.push({ slug: entry.slug, result: r });
-
-      // Banner emitted AFTER the leg succeeds so it appears alongside
-      // the per-company summary line and doesn't get scrolled off by
-      // sync chatter.
-      if (resolvedMode === "all" && entry.companyUid) {
-        emitNarrowHint({
-          companyUid: entry.companyUid,
-          syncMode: resolvedMode,
-          level: narrowHintLevel,
-        });
-      }
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      result.errors.push({ company: entry.slug, message });
-      result.perCompany.push({ slug: entry.slug, error: message });
-    }
-  }
-
-  return result;
-}
-
-interface PushPlanEntry {
-  slug: string;
-  shareOptions: ShareCallOptions;
-}
-
-/**
- * Drives `hq sync push --all`: same membership + canonical-person fanout as
- * pullAll, but each leg calls share() with the runner's bulk defaults
- * (skipUnchanged: true, propagateDeletes: true). Pure function with injected
- * deps so tests can drive it without network or filesystem.
- */
-export async function pushAll(
-  options: PushAllOptions,
-  deps: PushAllDeps,
-): Promise<PushAllResult> {
-  const memberships = await deps.vaultClient.listMyMemberships();
-  const persons = await deps.vaultClient.listPersonEntities();
-
-  const plan: PushPlanEntry[] = [];
-  for (const m of memberships) {
-    let slug = m.companyUid;
-    try {
-      const info = await deps.vaultClient.getEntity(m.companyUid);
-      if (info?.slug) slug = info.slug;
-    } catch {
-      // Best-effort — keep UID as the row label.
-    }
-    plan.push({
-      slug,
-      shareOptions: {
-        company: m.companyUid,
-        hqRoot: options.hqRoot,
-        paths: [path.join(options.hqRoot, "companies", slug)],
-        skipUnchanged: true,
-        propagateDeletes: true,
-        propagateDeletePolicy: resolveDeletePolicy(),
-        ...(options.onConflict ? { onConflict: options.onConflict } : {}),
-        ...(options.message ? { message: options.message } : {}),
-      },
-    });
-  }
-
-  const personal = options.skipPersonal ? null : pickCanonicalPerson(persons);
-  if (personal) {
-    plan.push({
-      slug: "personal",
-      shareOptions: {
-        company: personal.uid,
-        hqRoot: options.hqRoot,
-        paths: computePersonalVaultPaths(options.hqRoot),
-        personalMode: true,
-        journalSlug: PERSONAL_VAULT_JOURNAL_SLUG,
-        skipUnchanged: true,
-        propagateDeletes: true,
-        propagateDeletePolicy: resolveDeletePolicy(),
-        ...(options.onConflict ? { onConflict: options.onConflict } : {}),
-        ...(options.message ? { message: options.message } : {}),
-      },
-    });
-  }
-
-  const result: PushAllResult = {
-    attempted: 0,
-    filesUploaded: 0,
-    bytesUploaded: 0,
-    filesDeleted: 0,
-    filesExcludedByScope: 0,
-    errors: [],
-    perCompany: [],
-  };
-
-  for (const entry of plan) {
-    result.attempted += 1;
-    try {
-      const r = await deps.share(entry.shareOptions);
-      result.filesUploaded += r.filesUploaded;
-      result.bytesUploaded += r.bytesUploaded;
-      result.filesDeleted += r.filesDeleted;
-      result.filesExcludedByScope += r.filesExcludedByScope;
-      result.perCompany.push({ slug: entry.slug, result: r });
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      result.errors.push({ company: entry.slug, message });
-      result.perCompany.push({ slug: entry.slug, error: message });
-    }
-  }
-
-  return result;
-}
-
-/**
- * Resolve the canonical person entity UID for the logged-in user. Used by
- * `hq sync {push,pull,now} --personal` to target the personal vault without
- * the caller needing to know the UID. Throws a clean error if the user has
- * no person entity (typically means they haven't run `hq onboard`).
- */
-export async function resolveCanonicalPersonUid(
-  vaultClient: PullAllVaultClient,
-): Promise<string> {
-  const persons = await vaultClient.listPersonEntities();
-  const pick = pickCanonicalPerson(persons);
-  if (!pick) {
-    throw new Error(
-      "No personal vault found for the logged-in user. Run `hq onboard` " +
-        "first, or check `hq whoami` to confirm you're signed in to the " +
-        "right account.",
-    );
-  }
-  return pick.uid;
-}
-
-/**
- * Refuse `hq sync push --personal <path>` — the combination silently
- * bypasses `PERSONAL_VAULT_EXCLUDED_TOP_LEVEL` (which is only applied by
- * `computePersonalVaultPaths`), risking cross-scope upload of `companies/`,
- * `repos/`, `workspace/`, or `.git/` content to the personal vault. Real
- * incident (2026-05-21): a single command uploaded 196 `companies/{slug}/**`
- * objects to a personal vault before being killed. Cleanup required a
- * hand-rolled S3 sweep. Closes hq-cli#25.
- *
- * Refusal — not silent filtering — is intentional: explicit is better than
- * implicit guesswork, and the legitimate "I want to push a subset of my
- * personal vault" use case has a clean workaround (drop `--personal`, the
- * subset upload targets the active company via standard semantics).
- */
-export function assertNoPersonalPositionalPaths(opts: {
-  personal?: boolean;
-}, paths: string[] | undefined): void {
-  if (opts.personal && paths && paths.length > 0) {
-    throw new Error(
-      "`--personal` cannot be combined with explicit [paths]: " +
-        "positional paths bypass the PERSONAL_VAULT_EXCLUDED_TOP_LEVEL " +
-        "guard (skips .git/, companies/, repos/, workspace/), risking " +
-        "cross-scope upload of company data to the personal vault. " +
-        "Use bare `--personal` to push the whole personal scope, OR " +
-        "drop `--personal` to push specific paths to the active company.",
-    );
-  }
-}
-
-/**
- * Refuse ambiguous selector combinations. `--all`, `--personal`, and
- * `--company` are mutually exclusive — at most one may be set per
- * invocation; zero means "use the active company from .hq/config.json".
- */
-export function assertSingleSelector(opts: {
-  all?: boolean;
-  personal?: boolean;
-  company?: string;
-}, command: string): void {
-  const selectors: string[] = [];
-  if (opts.all) selectors.push("--all");
-  if (opts.personal) selectors.push("--personal");
-  if (opts.company) selectors.push(`--company ${opts.company}`);
-  if (selectors.length > 1) {
-    throw new Error(
-      `\`hq sync ${command}\` accepts at most one of --all, --personal, ` +
-        `--company; got: ${selectors.join(", ")}.`,
-    );
-  }
-}
-
-/**
- * Per-company pull resolution helper used by `hq sync pull --company <slug>`
- * (US-011 fix, 2026-05-21). Mirrors the inline lookup that `runNowSingle`
- * does for sync-now. Pulled out so the action handler stays thin AND so
- * unit tests can exercise the banner / strict-refusal decision without
- * spinning up commander + a real VaultClient.
- *
- * Input shape:
- *   - `targetCompany` — slug or UID the caller passed to `--company`. If
- *     undefined, the helper short-circuits to a "no resolution" result
- *     (the action handler falls back to .hq/config.json via sync()).
- *   - `client` — minimal VaultClient surface: listMyMemberships + entity.get
- *     + getMembershipSyncConfig.
- *
- * Output: `{ resolvedCompanyUid, resolvedMode }` — either may be undefined
- * if the membership / sync-config call failed. Both undefined is a clean
- * degradation — the caller pulls without a banner.
- */
-export interface PerCompanyPullResolveClient {
-  listMyMemberships(): Promise<Array<{ companyUid: string; membershipKey: string }>>;
-  getMembershipSyncConfig(
-    membershipKey: string,
-  ): Promise<{ syncMode: MembershipSyncConfig["syncMode"] }>;
-  entity: { get(uid: string): Promise<{ slug?: string }> };
-}
-
-export interface PerCompanyPullResolveResult {
-  resolvedCompanyUid: string | undefined;
-  resolvedMode: MembershipSyncConfig["syncMode"] | undefined;
-}
-
-export async function resolvePerCompanyPullPlan(
-  client: PerCompanyPullResolveClient,
-  targetCompany: string | undefined,
-): Promise<PerCompanyPullResolveResult> {
-  if (!targetCompany) return { resolvedCompanyUid: undefined, resolvedMode: undefined };
-  try {
-    const memberships = await client.listMyMemberships();
-    // Direct UID / membershipKey match first (cheapest).
-    const direct = memberships.find(
-      (m) => m.companyUid === targetCompany || m.membershipKey === targetCompany,
-    );
-    if (direct) {
-      let mode: MembershipSyncConfig["syncMode"] | undefined;
-      try {
-        const cfg = await client.getMembershipSyncConfig(direct.membershipKey);
-        mode = cfg.syncMode;
-      } catch {
-        mode = undefined;
-      }
-      return { resolvedCompanyUid: direct.companyUid, resolvedMode: mode };
-    }
-    // Slug match — listMyMemberships returns companyUid only, so fan out
-    // entity.get to find the row whose slug matches the caller's input.
-    for (const m of memberships) {
-      try {
-        const entity = await client.entity.get(m.companyUid);
-        if (entity.slug === targetCompany) {
-          let mode: MembershipSyncConfig["syncMode"] | undefined;
-          try {
-            const cfg = await client.getMembershipSyncConfig(m.membershipKey);
-            mode = cfg.syncMode;
-          } catch {
-            mode = undefined;
-          }
-          return { resolvedCompanyUid: m.companyUid, resolvedMode: mode };
-        }
-      } catch {
-        // Entity not visible — skip and continue. Worst case the loop ends
-        // with no match and we return undefined for both — the pull still
-        // proceeds, banner just stays quiet.
-      }
-    }
-  } catch {
-    // listMyMemberships failed — degrade silently. Sync still works without
-    // the banner; this matches the runPullAll catch behavior.
-  }
-  return { resolvedCompanyUid: undefined, resolvedMode: undefined };
-}
-
-/** Read the active company slug/uid from `.hq/config.json` (best-effort). */
-function readActiveCompany(hqRoot: string): string | undefined {
-  try {
-    const cfg = JSON.parse(
-      fs.readFileSync(path.join(hqRoot, ".hq", "config.json"), "utf-8"),
-    ) as { activeCompany?: unknown };
-    return typeof cfg?.activeCompany === "string" ? cfg.activeCompany : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-/**
- * Resolve the effective PULL scope (DEV-1768) for a single foreground pull
- * (`hq sync pull` / `hq sync now`), so the membership's REAL syncMode +
- * prefixSet are threaded into `sync()`. Without this the CLI ran `syncMode:
- * "all"` and stamped an all-mode PullRecord that wedged the next menubar sync.
- *
- * Delegates to the shared `resolvePullScope` (same resolver the runner uses),
- * which degrades to `all` on any failure — so a transient blip never narrows
- * scope. Returns `undefined` only when no company can be resolved at all (then
- * `sync()` resolves the active company itself and pulls `all`, as before).
- */
-async function resolveCliPullScope(
-  client: VaultClient,
-  companyRef: string | undefined,
-  hqRoot: string,
-): Promise<PullScope | undefined> {
-  const ref = companyRef ?? readActiveCompany(hqRoot);
-  if (!ref) return undefined;
-  // Map ref (slug OR uid) → { uid, slug }: resolvePullScope needs the slug to
-  // normalize slug-anchored grant paths in shared mode.
-  let companyUid = ref;
-  let slug = ref;
-  try {
-    const memberships = await client.listMyMemberships();
-    const direct = memberships.find(
-      (m) => m.companyUid === ref || m.membershipKey === ref,
-    );
-    if (direct) {
-      companyUid = direct.companyUid;
-      const ent = await client.entity.get(direct.companyUid).catch(() => null);
-      if (ent?.slug) slug = ent.slug;
-    } else {
-      for (const m of memberships) {
-        const ent = await client.entity.get(m.companyUid).catch(() => null);
-        if (ent?.slug === ref) {
-          companyUid = m.companyUid;
-          slug = ent.slug;
-          break;
-        }
-      }
-    }
-  } catch {
-    // Can't resolve the membership set — degrade to no explicit scope.
-    return undefined;
-  }
-  return resolvePullScope(client, companyUid, slug, hqRoot);
-}
-
-export function registerCloudCommands(program: Command): void {
-  program
-    .command("push")
-    .description("Push local file(s) to the company vault on S3")
-    .argument("[paths...]", "Paths to push (defaults to current directory)")
-    .option(
-      "--hq-root <path>",
-      `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`,
-      DEFAULT_HQ_ROOT,
-    )
-    .option(
-      "--company <slug>",
-      "Company slug or UID (defaults to active company in .hq/config.json)",
-    )
-    .option(
-      "--lock-timeout <seconds>",
-      "Maximum wait for another active HQ operation (default: 300; 0 = refuse immediately)",
-    )
-    .option(
-      "--message <msg>",
-      "Optional message attached to journal entries for these uploads",
-    )
-    .option(
-      "--on-conflict <strategy>",
-      "Conflict strategy: overwrite | keep | abort (omit for interactive)",
-    )
-    .option(
-      "--creds-from-stdin",
-      "Read a pre-vended EntityContext as JSON from stdin instead of vending " +
-        "via the cached Cognito session. Use when the caller (e.g. AppBar HQ " +
-        "Sync) has its own STS pipeline (`/sts/vend-child` with task scope) " +
-        "and just needs share()'s upload mechanics. The caller is responsible " +
-        "for vending credentials with enough TTL for the run.",
-    )
-    .option(
-      "--json",
-      "Emit each share()-level event as a JSON Lines record on stderr (one " +
-        "JSON object per line) instead of human-readable console output. A " +
-        "synthetic `{type:\"complete\",...}` line is appended at the end with " +
-        "the final ShareResult. Subprocess callers parse these to render their " +
-        "own UI (e.g. AppBar Tauri events).",
-    )
-    .option(
-      "--all",
-      "Push every company you are a member of plus your personal vault. " +
-        "Company targets push `<hq-root>/companies/<slug>/`; personal pushes " +
-        "every top-level entry under <hq-root> minus the excluded set " +
-        "(.git, companies, repos, workspace). Implies --skip-unchanged + " +
-        "--propagate-deletes. Mutually exclusive with --company, --personal, " +
-        "and any explicit [paths].",
-    )
-    .option(
-      "--personal",
-      "Push to the caller's canonical personal vault (resolved from the " +
-        "cached Cognito session). When no [paths] are given, defaults to " +
-        "every top-level entry under <hq-root> minus the excluded set " +
-        "(.git, companies, repos, workspace) — same scope as `--all`'s " +
-        "personal slot. Mutually exclusive with --company and --all.",
-    )
-    .option(
-      "--no-personal",
-      "In `--all` mode, skip the canonical-person leg of the fanout — " +
-        "only push to the caller's company memberships. Mirrors the " +
-        "upstream `hq-sync-runner --skip-personal` flag (hq-cloud 5.25.0); " +
-        "wired so the AppBar HQ Sync menubar can drop personal sync via " +
-        "a toggle, and so CLI users can opt out one-off. Ignored outside " +
-        "`--all`.",
-    )
-    .action(
-      async (
-        paths: string[],
-        options: CommonSyncOptions & {
-          message?: string;
-          onConflict?: ConflictStrategy;
-          credsFromStdin?: boolean;
-          json?: boolean;
-          all?: boolean;
-          personal?: boolean;
-        },
-      ) => {
-        try {
-          configureSyncLockTimeout(options.lockTimeout);
-          assertSingleSelector(options, "push");
-        } catch (err) {
-          console.error(
-            chalk.red("\n✗ Push failed:"),
-            err instanceof Error ? err.message : String(err),
-          );
-          process.exit(1);
-        }
-        if (options.all) {
-          if (paths && paths.length > 0) {
-            console.error(
-              chalk.red("\n✗ Push failed:"),
-              "`--all` cannot be combined with explicit [paths]. " +
-                "Drop the paths to fan out to every membership + personal, " +
-                "or drop --all to push specific paths to a single target.",
-            );
-            process.exit(1);
-          }
-          if (options.credsFromStdin) {
-            console.error(
-              chalk.red("\n✗ Push failed:"),
-              "`--all` cannot be combined with --creds-from-stdin (fanout " +
-                "needs to vend per-target credentials via the cached Cognito " +
-                "session). Run separate `--creds-from-stdin` invocations per " +
-                "target instead.",
-            );
-            process.exit(1);
-          }
-          // `options.personal === false` happens when the user passed
-          // `--no-personal` (Commander's auto-negation of the `--personal`
-          // selector). In `--all` mode that means "skip the personal leg of
-          // the fanout" — wired through to `pushAll.skipPersonal`. Outside
-          // `--all` the flag has no effect (logged above as part of the
-          // option's help text).
-          await runPushAll(
-            options.hqRoot,
-            options.message,
-            options.onConflict,
-            options.personal === false,
-          );
-          return;
-        }
-        const jsonMode = options.json === true;
-        // Suppress the human banner/result output in JSON mode — the parent
-        // process renders its own UI from the stderr ndjson stream.
-        const log = (msg: string): void => {
-          if (!jsonMode) console.log(msg);
-        };
-        const emitJson = (event: Record<string, unknown>): void => {
-          process.stderr.write(JSON.stringify(event) + "\n");
-        };
-
-        try {
-          if (options.personal && options.credsFromStdin) {
-            throw new Error(
-              "`--personal` cannot be combined with --creds-from-stdin: " +
-                "--personal resolves the canonical person UID via the cached " +
-                "Cognito session, while --creds-from-stdin expects the caller " +
-                "to have already resolved entity + credentials. Pick one.",
-            );
-          }
-          // Closes hq-cli#25 — see `assertNoPersonalPositionalPaths` doc-block.
-          assertNoPersonalPositionalPaths(options, paths);
-
-          log(chalk.bold("\nHQ Sync — Push"));
-          log(`  HQ root:  ${options.hqRoot}`);
-
-          // Resolve credentials. Two paths:
-          //   1. --creds-from-stdin: parse JSON EntityContext from stdin (the
-          //      AppBar shell-out contract — vend-child upstream, pipe in here).
-          //   2. default: vend via cached Cognito session (the human CLI path).
-          let entityContext: EntityContext | undefined;
-          let vaultConfig: ReturnType<typeof buildVaultConfig> | undefined;
-
-          if (options.credsFromStdin) {
-            if (process.stdin.isTTY) {
-              throw new Error(
-                "--creds-from-stdin requires JSON on stdin, but stdin is a " +
-                  "TTY. Pipe the EntityContext JSON via subprocess stdin " +
-                  "(e.g. `echo '{...}' | hq sync push --creds-from-stdin ...`).",
-              );
-            }
-            const raw = await readAllStdin();
-            try {
-              entityContext = JSON.parse(raw) as EntityContext;
-            } catch (e) {
-              throw new Error(
-                `--creds-from-stdin: failed to parse stdin as JSON: ${
-                  e instanceof Error ? e.message : String(e)
-                }`,
-              );
-            }
-          } else {
-            const accessToken = await ensureCognitoToken();
-            vaultConfig = buildVaultConfig(accessToken);
-          }
-
-          // Resolve the target. For `--personal`, look up the caller's
-          // canonical person entity and force personalMode + journalSlug so
-          // share() lands files at hqRoot directly (no companies/<slug>/
-          // prefix). For everything else, the company is whatever the user
-          // passed or the active company from .hq/config.json.
-          let targetCompany = options.company;
-          let personalMode = false;
-          let journalSlug: string | undefined;
-          if (options.personal) {
-            const client = new VaultClient(vaultConfig!);
-            targetCompany = await resolveCanonicalPersonUid({
-              listMyMemberships: () => client.listMyMemberships(),
-              listPersonEntities: () => client.entity.listByType("person"),
-              getEntity: async () => null,
-            });
-            personalMode = true;
-            journalSlug = PERSONAL_VAULT_JOURNAL_SLUG;
-          }
-
-          // Default paths. For `--personal` with no explicit paths, default to
-          // the canonical personal-vault top-level scope so re-runs from a
-          // user shell push the same surface as `--all`'s personal slot.
-          // Otherwise preserve the historical "default to cwd" semantics so
-          // `hq sync push <file>` and bare `hq sync push` from inside the
-          // company tree both work as before.
-          const targetPaths =
-            paths && paths.length > 0
-              ? paths
-              : options.personal
-                ? computePersonalVaultPaths(options.hqRoot)
-                : [process.cwd()];
-
-          log(
-            `  Company:  ${
-              options.personal
-                ? `(personal: ${targetCompany})`
-                : (options.company ?? "(from .hq/config.json or stdin)")
-            }`,
-          );
-          log(`  Paths:    ${targetPaths.join(", ")}\n`);
-
-          // In JSON mode, forward every share() event verbatim to stderr as
-          // ndjson. In human mode, share()'s defaultConsoleLogger handles the
-          // rendering (no onEvent → falls through to stdout/stderr printing).
-          const onEvent = jsonMode
-            ? (event: SyncProgressEvent): void =>
-                emitJson(event as unknown as Record<string, unknown>)
-            : undefined;
-
-          // Stamp every uploaded object's S3 user metadata with the syncing
-          // user's Cognito identity (`Metadata['created-by']`). The hq-console
-          // vault UI's CREATED BY column reads this back via HEAD; without it,
-          // every row renders `—`. Resolved best-effort from the cached
-          // idToken — pre-vended `--creds-from-stdin` paths still get author
-          // attribution as long as the caller is logged in locally.
-          const author = resolveUploadAuthorFromCache();
-
-          const result = await share({
-            paths: targetPaths,
-            company: targetCompany,
-            message: options.message,
-            onConflict: options.onConflict,
-            vaultConfig,
-            entityContext,
-            hqRoot: options.hqRoot,
-            onEvent,
-            ...(personalMode ? { personalMode: true } : {}),
-            ...(journalSlug !== undefined ? { journalSlug } : {}),
-            ...(author ? { author } : {}),
-          });
-
-          if (jsonMode) {
-            // Synthetic terminal event so subprocess consumers can read final
-            // counts without summing per-file events. Distinguished from
-            // SyncProgressEvent by `type:"complete"` (not in the share()
-            // event schema — added at the CLI seam).
-            emitJson({
-              type: "complete",
-              filesUploaded: result.filesUploaded,
-              bytesUploaded: result.bytesUploaded,
-              filesSkipped: result.filesSkipped,
-              conflictPaths: result.conflictPaths,
-              aborted: result.aborted,
-            });
-          }
-
-          if (result.aborted) {
-            log(
-              chalk.yellow(
-                `\n⚠ Push aborted (${result.filesUploaded} uploaded, ${result.filesSkipped} skipped)`,
-              ),
-            );
-            process.exit(1);
-          }
-
-          if (result.filesExcludedByScope > 0) {
-            log(
-              chalk.yellow(
-                `\n⚠ Pushed ${result.filesUploaded} file(s) (${formatBytes(result.bytesUploaded)}, ` +
-                  `${result.filesSkipped} skipped, ${result.filesExcludedByScope} scope-excluded)`,
-              ),
-            );
-            log(chalk.yellow(scopeExcludedWarning(result.filesExcludedByScope)!));
-          } else {
-            log(
-              chalk.green(
-                `\n✓ Pushed ${result.filesUploaded} file(s) (${formatBytes(result.bytesUploaded)}, ${result.filesSkipped} skipped)`,
-              ),
-            );
-          }
-        } catch (err) {
-          const message = err instanceof Error ? err.message : String(err);
-          if (jsonMode) {
-            // In JSON mode, the parent process is parsing stderr for ndjson —
-            // human-formatted error lines would corrupt the stream. Emit a
-            // structured `fatal` event instead and let the parent surface it.
-            emitJson({ type: "fatal", message });
-          } else {
-            console.error(chalk.red("\n✗ Push failed:"), message);
-          }
-          process.exit(1);
-        }
-      },
-    );
-
-  program
-    .command("pull")
-    .description("Pull permitted files from the company vault to local HQ")
-    .option(
-      "--hq-root <path>",
-      `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`,
-      DEFAULT_HQ_ROOT,
-    )
-    .option(
-      "--company <slug>",
-      "Company slug or UID (defaults to active company in .hq/config.json)",
-    )
-    .option(
-      "--lock-timeout <seconds>",
-      "Maximum wait for another active HQ operation (default: 300; 0 = refuse immediately)",
-    )
-    .option(
-      "--on-conflict <strategy>",
-      "Conflict strategy: overwrite | keep | abort (omit for interactive)",
-    )
-    .option(
-      "--all",
-      "Pull every company you are a member of plus your personal vault " +
-        "into <hq-root>. Companies land at <hq-root>/companies/<slug>; " +
-        "the personal vault syncs at <hq-root>. Mutually exclusive with " +
-        "--company and --personal.",
-    )
-    .option(
-      "--personal",
-      "Pull the caller's canonical personal vault into <hq-root> directly " +
-        "(no companies/<slug>/ prefix). Resolves the person UID automatically " +
-        "from the cached Cognito session. Mutually exclusive with --company " +
-        "and --all.",
-    )
-    .option(
-      "--no-personal",
-      "In `--all` mode, skip the canonical-person leg of the fanout — " +
-        "only pull the caller's company memberships. Mirrors the upstream " +
-        "`hq-sync-runner --skip-personal` flag (hq-cloud 5.25.0). Ignored " +
-        "outside `--all`.",
-    )
-    .option(
-      "--mode-all",
-      "US-011: opt out of the strict narrow-hint refusal for this run. " +
-        "Has no effect today (default narrow-hint level is 'hint'); " +
-        "wired so future hq-core-staging releases can flip the default to " +
-        "'strict' without re-touching this command.",
-    )
-    .option(
-      "--force-scope-shrink",
-      "When a scope shrink would un-track locally-modified files (e.g. after " +
-        "narrowing from all → shared), proceed anyway. Dirty files are KEPT on " +
-        "disk and only un-tracked from sync; clean out-of-scope files are " +
-        "quarantined under .hq/scope-quarantine/ (recoverable).",
-    )
-    .action(
-      async (
-        options: CommonSyncOptions & {
-          onConflict?: ConflictStrategy;
-          all?: boolean;
-          personal?: boolean;
-          modeAll?: boolean;
-          forceScopeShrink?: boolean;
-        },
-      ) => {
-        try {
-          configureSyncLockTimeout(options.lockTimeout);
-          assertSingleSelector(options, "pull");
-        } catch (err) {
-          console.error(
-            chalk.red("\n✗ Pull failed:"),
-            err instanceof Error ? err.message : String(err),
-          );
-          process.exit(1);
-        }
-        if (options.all) {
-          // `options.personal === false` is Commander's auto-negation of
-          // `--personal`; in `--all` mode that means "drop the personal
-          // leg from the fanout" (see `--no-personal` option above).
-          await runPullAll(
-            options.hqRoot,
-            options.onConflict,
-            options.modeAll === true,
-            options.personal === false,
-            options.forceScopeShrink === true,
-          );
-          return;
-        }
-        if (options.personal) {
-          await runPullPersonal(options.hqRoot, options.onConflict);
-          return;
-        }
-        try {
-          console.log(chalk.bold("\nHQ Sync — Pull"));
-          console.log(`  HQ root:  ${options.hqRoot}`);
-          console.log(`  Company:  ${options.company ?? "(from .hq/config.json)"}\n`);
-
-          const accessToken = await ensureCognitoToken();
-          const vaultConfig = buildVaultConfig(accessToken);
-
-          // US-011 (2026-05-21 fix): resolve the caller's sync-config for
-          // the targeted membership BEFORE the pull, so we can (a) emit the
-          // narrow-hint banner after success if still on all-mode and
-          // (b) respect strict-mode refusal mirror of the --all + sync-now
-          // paths. Failure to resolve degrades silently — pull still works,
-          // banner just stays quiet (same as the catch in runPullAll).
-          const narrowHintLevel: BannerLevel = resolveBannerLevel();
-          const pullClient = new VaultClient(vaultConfig);
-          const { resolvedCompanyUid, resolvedMode } =
-            await resolvePerCompanyPullPlan(pullClient, options.company);
-          // DEV-1768: resolve the REAL effective scope (mode + prefixSet) and
-          // thread it into the pull below — not just the banner. Best-effort;
-          // degrades to "all" inside the resolver on any failure.
-          const pullScope = await resolveCliPullScope(
-            pullClient,
-            options.company,
-            options.hqRoot,
-          );
-
-          // Strict-mode refusal: matches runPullAll + runNowSingle behavior.
-          // Default banner level is 'hint' which never triggers refusal —
-          // wired now so future hq-core-staging releases can flip the
-          // default to 'strict' without re-touching this command.
-          if (
-            resolvedMode === "all" &&
-            isStrictRefusal(resolvedMode, narrowHintLevel) &&
-            options.modeAll !== true &&
-            resolvedCompanyUid
-          ) {
-            emitNarrowHint({
-              companyUid: resolvedCompanyUid,
-              syncMode: resolvedMode,
-              level: narrowHintLevel,
-            });
-            console.error(
-              chalk.red(
-                "\n✗ Pull refused: strict narrow-hint mode is on and this " +
-                  "membership still pulls everything. Run `hq sync narrow --apply` " +
-                  "to migrate, or re-run with --mode-all.",
-              ),
-            );
-            process.exit(1);
-          }
-
-          const excludePrefixes = readScopeExcludePrefixes(pullScope);
-          const result = await sync({
-            company: options.company,
-            onConflict: options.onConflict,
-            vaultConfig,
-            hqRoot: options.hqRoot,
-            ...(pullScope?.syncMode !== undefined
-              ? { syncMode: pullScope.syncMode }
-              : {}),
-            ...(pullScope?.prefixSet !== undefined
-              ? { prefixSet: pullScope.prefixSet }
-              : {}),
-            // Sessions-exclusion: never materialize excluded prefixes even for
-            // a wide-STS owner.
-            ...(excludePrefixes ? { excludePrefixes } : {}),
-            ...(options.forceScopeShrink ? { forceScopeShrink: true } : {}),
-          });
-
-          if (result.aborted) {
-            console.log(
-              chalk.yellow(
-                `\n⚠ Pull aborted (${result.filesDownloaded} downloaded, ${result.filesSkipped} skipped, ${result.conflicts} conflicts)`,
-              ),
-            );
-            process.exit(1);
-          }
-
-          console.log(
-            chalk.green(
-              `\n✓ Pulled ${result.filesDownloaded} file(s) (${formatBytes(result.bytesDownloaded)}, ${result.filesSkipped} skipped, ${result.conflicts} conflicts)`,
-            ),
-          );
-
-          // US-011 (2026-05-21 fix): emit the hint banner after success
-          // so it appears alongside the summary line. Mirrors the wiring
-          // in runPullAll (cloud.ts:331) and runNowSingle (cloud.ts:1371).
-          if (resolvedMode === "all" && resolvedCompanyUid) {
-            emitNarrowHint({
-              companyUid: resolvedCompanyUid,
-              syncMode: resolvedMode,
-              level: narrowHintLevel,
-            });
-          }
-        } catch (err) {
-          console.error(
-            chalk.red("\n✗ Pull failed:"),
-            err instanceof Error ? err.message : String(err),
-          );
-          process.exit(1);
-        }
-      },
-    );
-
-  program
-    .command("status")
-    .description("Show local sync journal summary")
-    .option(
-      "--hq-root <path>",
-      `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`,
-      DEFAULT_HQ_ROOT,
-    )
-    .action((options: { hqRoot: string }) => {
-      try {
-        // The engine SHARDS the journal by slug — the personal-vault fanout
-        // slot, one shard per cloud company, and the legacy "personal" shard.
-        // Enumerate EVERY shard the engine can write (via the engine's own
-        // `listJournals`) rather than reconstructing a single path: the old
-        // code passed the HQ-root PATH where a slug was expected, so it always
-        // looked at `sync-journal._Users_<user>_hq.json` — a slug the engine
-        // never writes — and printed "No sync journal yet" right after a
-        // successful sync (feedback_9fbf1f82 / feedback_46288b7b).
-        const journals = listJournals();
-
-        if (journals.length === 0) {
-          console.log(
-            chalk.dim(
-              "No sync journal yet — run `hq sync now`, `hq sync push`, or `hq sync pull` to create one.",
-            ),
-          );
-          console.log(
-            chalk.dim(`  Looked in: ${getStateDir()} (sync-journal.*.json)`),
-          );
-          return;
-        }
-
-        const configPath = path.join(options.hqRoot, ".hq", "config.json");
-        let activeCompany: string | undefined;
-        if (fs.existsSync(configPath)) {
-          try {
-            const cfg = JSON.parse(fs.readFileSync(configPath, "utf-8"));
-            activeCompany = cfg.activeCompany;
-          } catch {
-            // ignore
-          }
-        }
-
-        let grandFiles = 0;
-        let grandBytes = 0;
-        let grandLastSync = "";
-
-        console.log(chalk.bold("\nHQ Sync — Status"));
-        console.log(`  HQ root:        ${options.hqRoot}`);
-        console.log(`  Active company: ${activeCompany ?? chalk.dim("(none)")}`);
-        console.log(`  Journals:       ${journals.length}`);
-
-        for (const j of journals) {
-          const entries = Object.entries(j.journal.files ?? {});
-          // Tombstones record removed files — exclude them from "tracked".
-          const live = entries.filter(([, entry]) => !entry.removedAt);
-          const bytes = live.reduce(
-            (acc, [, entry]) => acc + (entry.size ?? 0),
-            0,
-          );
-          const lastSync =
-            j.journal.lastSync ||
-            live
-              .map(([, entry]) => entry.syncedAt)
-              .filter((t): t is string => typeof t === "string")
-              .sort()
-              .at(-1) ||
-            "never";
-
-          grandFiles += live.length;
-          grandBytes += bytes;
-          if (lastSync !== "never" && lastSync > grandLastSync) {
-            grandLastSync = lastSync;
-          }
-
-          console.log(`\n  • ${scopeLabel(j.slug)}`);
-          console.log(`      Tracked files: ${live.length}`);
-          console.log(`      Total size:    ${formatBytes(bytes)}`);
-          console.log(`      Last sync:     ${lastSync}`);
-          console.log(chalk.dim(`      Journal:       ${j.path}`));
-        }
-
-        if (journals.length > 1) {
-          console.log(chalk.bold("\n  All scopes"));
-          console.log(`      Tracked files: ${grandFiles}`);
-          console.log(`      Total size:    ${formatBytes(grandBytes)}`);
-          console.log(`      Last sync:     ${grandLastSync || "never"}`);
-        }
-      } catch (err) {
-        console.error(
-          chalk.red("✗ Status failed:"),
-          err instanceof Error ? err.message : String(err),
-        );
-        process.exit(1);
-      }
-    });
-
-  program
-    .command("now")
-    .description(
-      "Bidirectional sync: push local changes, then pull remote updates " +
-        "(mirrors AppBar HQ Sync's \"Sync Now\" button)",
-    )
-    .option(
-      "--hq-root <path>",
-      `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`,
-      DEFAULT_HQ_ROOT,
-    )
-    .option(
-      "--company <slug>",
-      "Company slug or UID (defaults to active company in .hq/config.json)",
-    )
-    .option(
-      "--lock-timeout <seconds>",
-      "Maximum wait for another active HQ operation (default: 300; 0 = refuse immediately)",
-    )
-    .option(
-      "--message <msg>",
-      "Optional message attached to journal entries for the push leg",
-    )
-    .option(
-      "--on-conflict <strategy>",
-      "Conflict strategy: overwrite | keep | abort (omit for interactive)",
-    )
-    .option(
-      "--all",
-      "Sync every company you are a member of plus your personal vault " +
-        "(pushAll then pullAll). Mutually exclusive with --company and " +
-        "--personal.",
-    )
-    .option(
-      "--personal",
-      "Sync the caller's canonical personal vault bidirectionally. " +
-        "Mutually exclusive with --company and --all.",
-    )
-    .option(
-      "--no-personal",
-      "In `--all` mode, skip the canonical-person leg of both the push " +
-        "and pull fanouts — only sync the caller's company memberships. " +
-        "Mirrors the upstream `hq-sync-runner --skip-personal` flag " +
-        "(hq-cloud 5.25.0). Ignored outside `--all`.",
-    )
-    .option(
-      "--mode-all",
-      "US-011: opt out of the strict narrow-hint refusal for this run. " +
-        "No-op today; wired so future hq-core-staging releases can flip " +
-        "the default narrow-hint level to 'strict'.",
-    )
-    .option(
-      "--force-scope-shrink",
-      "When a scope shrink would un-track locally-modified files, proceed " +
-        "anyway. Dirty files are KEPT on disk (only un-tracked); clean " +
-        "out-of-scope files are quarantined under .hq/scope-quarantine/.",
-    )
-    .action(
-      async (
-        options: CommonSyncOptions & {
-          onConflict?: ConflictStrategy;
-          message?: string;
-          all?: boolean;
-          personal?: boolean;
-          modeAll?: boolean;
-          forceScopeShrink?: boolean;
-        },
-      ) => {
-        try {
-          configureSyncLockTimeout(options.lockTimeout);
-          assertSingleSelector(options, "now");
-          if (options.all) {
-            // `options.personal === false` is Commander's auto-negation
-            // of `--personal`; in `--all` mode that means "drop the
-            // personal leg from both legs of the bidirectional fanout"
-            // (see `--no-personal` option above).
-            await runNowAll(
-              options.hqRoot,
-              options.message,
-              options.onConflict,
-              options.modeAll === true,
-              options.personal === false,
-              options.forceScopeShrink === true,
-            );
-            return;
-          }
-          await runNowSingle(
-            options.hqRoot,
-            options.company,
-            options.personal === true,
-            options.message,
-            options.onConflict,
-            options.modeAll === true,
-            options.forceScopeShrink === true,
-          );
-        } catch (err) {
-          console.error(
-            chalk.red("\n✗ Sync now failed:"),
-            err instanceof Error ? err.message : String(err),
-          );
-          process.exit(1);
-        }
-      },
-    );
-}
-
-async function runPullAll(
-  hqRoot: string,
-  onConflict?: ConflictStrategy,
-  modeAllOverride?: boolean,
-  skipPersonal?: boolean,
-  forceScopeShrink?: boolean,
-): Promise<void> {
-  console.log(chalk.bold("\nHQ Sync — Pull (all)"));
-  console.log(`  HQ root:  ${hqRoot}`);
-  console.log(`  Strategy: ${onConflict ?? "(interactive)"}`);
-  if (skipPersonal) {
-    console.log(`  Personal: skipped (--no-personal)`);
-  }
-  console.log("");
-
-  let result: PullAllResult;
-  try {
-    const accessToken = await ensureCognitoToken();
-    const vaultConfig = buildVaultConfig(accessToken);
-    const realClient = new VaultClient(vaultConfig);
-
-    const adapter: PullAllVaultClient = {
-      listMyMemberships: () => realClient.listMyMemberships(),
-      listPersonEntities: () => realClient.entity.listByType("person"),
-      getEntity: async (uid: string) => {
-        try {
-          return await realClient.entity.get(uid);
-        } catch {
-          return null;
-        }
-      },
-      getMembershipSyncConfig: (id: string) =>
-        realClient.getMembershipSyncConfig(id),
-      listMyExplicitGrants: (companyUid: string) =>
-        realClient.listMyExplicitGrants(companyUid),
-    };
-
-    result = await pullAll(
-      {
-        hqRoot,
-        ...(onConflict ? { onConflict } : {}),
-        narrowHintLevel: resolveBannerLevel(),
-        ...(modeAllOverride ? { modeAllOverride: true } : {}),
-        ...(skipPersonal ? { skipPersonal: true } : {}),
-        ...(forceScopeShrink ? { forceScopeShrink: true } : {}),
-      },
-      {
-        vaultClient: adapter,
-        // DEV-1768: resolve each company's REAL pull scope (mode + prefixSet)
-        // via the shared resolver, so the actual pull is scoped — the CLI no
-        // longer seeds an all-mode PullRecord that wedges the menubar runner.
-        resolveScope: (companyUid: string, slug: string) =>
-          resolvePullScope(realClient, companyUid, slug, hqRoot),
-        sync: (opts) =>
-          sync({
-            company: opts.company,
-            hqRoot: opts.hqRoot,
-            vaultConfig,
-            ...(opts.onConflict ? { onConflict: opts.onConflict } : {}),
-            ...(opts.personalMode !== undefined
-              ? { personalMode: opts.personalMode }
-              : {}),
-            ...(opts.journalSlug !== undefined
-              ? { journalSlug: opts.journalSlug }
-              : {}),
-            ...(opts.syncMode !== undefined ? { syncMode: opts.syncMode } : {}),
-            ...(opts.prefixSet !== undefined ? { prefixSet: opts.prefixSet } : {}),
-            // Sessions-exclusion: forward the per-company excludePrefixes that
-            // pullAll stamped onto SyncCallOptions into the real hq-cloud sync().
-            ...(opts.excludePrefixes?.length
-              ? { excludePrefixes: opts.excludePrefixes }
-              : {}),
-            ...(opts.forceScopeShrink ? { forceScopeShrink: true } : {}),
-          }),
-      },
-    );
-  } catch (err) {
-    console.error(
-      chalk.red("\n✗ Pull-all failed:"),
-      err instanceof Error ? err.message : String(err),
-    );
-    process.exit(1);
-  }
-
-  for (const row of result.perCompany) {
-    if (row.error) {
-      console.log(chalk.red(`  ✗ ${row.slug}: ${row.error}`));
-    } else if (row.result) {
-      const r = row.result;
-      const status = r.aborted ? chalk.yellow("⚠") : chalk.green("✓");
-      console.log(
-        `  ${status} ${row.slug}: ${r.filesDownloaded} file(s), ` +
-          `${formatBytes(r.bytesDownloaded)}, ` +
-          `${r.filesSkipped} skipped, ${r.conflicts} conflict(s)` +
-          (r.aborted ? " — aborted" : ""),
-      );
-    }
-  }
-
-  const errored = result.errors.length;
-  const summary =
-    `\nPulled ${result.filesDownloaded} file(s) ` +
-    `(${formatBytes(result.bytesDownloaded)}) across ${result.attempted} ` +
-    `target(s); ${result.conflicts} conflict(s); ${errored} error(s)`;
-  console.log(errored > 0 ? chalk.yellow(summary) : chalk.green(summary));
-  if (errored > 0) process.exit(1);
-}
-
-async function runPullPersonal(
-  hqRoot: string,
-  onConflict?: ConflictStrategy,
-): Promise<void> {
-  console.log(chalk.bold("\nHQ Sync — Pull (personal)"));
-  console.log(`  HQ root:  ${hqRoot}`);
-  console.log(`  Strategy: ${onConflict ?? "(interactive)"}\n`);
-
-  try {
-    const accessToken = await ensureCognitoToken();
-    const vaultConfig = buildVaultConfig(accessToken);
-    const client = new VaultClient(vaultConfig);
-    const personalUid = await resolveCanonicalPersonUid({
-      listMyMemberships: () => client.listMyMemberships(),
-      listPersonEntities: () => client.entity.listByType("person"),
-      getEntity: async () => null,
-    });
-
-    const result = await sync({
-      company: personalUid,
-      ...(onConflict ? { onConflict } : {}),
-      vaultConfig,
-      hqRoot,
-      personalMode: true,
-      journalSlug: PERSONAL_VAULT_JOURNAL_SLUG,
-    });
-
-    if (result.aborted) {
-      console.log(
-        chalk.yellow(
-          `\n⚠ Pull aborted (${result.filesDownloaded} downloaded, ${result.filesSkipped} skipped, ${result.conflicts} conflicts)`,
-        ),
-      );
-      process.exit(1);
-    }
-
-    console.log(
-      chalk.green(
-        `\n✓ Pulled ${result.filesDownloaded} file(s) (${formatBytes(result.bytesDownloaded)}, ${result.filesSkipped} skipped, ${result.conflicts} conflicts)`,
-      ),
-    );
-  } catch (err) {
-    console.error(
-      chalk.red("\n✗ Pull (personal) failed:"),
-      err instanceof Error ? err.message : String(err),
-    );
-    process.exit(1);
-  }
-}
-
-async function runPushAll(
-  hqRoot: string,
-  message?: string,
-  onConflict?: ConflictStrategy,
-  skipPersonal?: boolean,
-): Promise<void> {
-  console.log(chalk.bold("\nHQ Sync — Push (all)"));
-  console.log(`  HQ root:  ${hqRoot}`);
-  console.log(`  Strategy: ${onConflict ?? "(interactive)"}`);
-  if (skipPersonal) {
-    console.log(`  Personal: skipped (--no-personal)`);
-  }
-  console.log("");
-
-  let result: PushAllResult;
-  try {
-    const accessToken = await ensureCognitoToken();
-    const vaultConfig = buildVaultConfig(accessToken);
-    const realClient = new VaultClient(vaultConfig);
-    const author = resolveUploadAuthorFromCache();
-
-    const adapter: PullAllVaultClient = {
-      listMyMemberships: () => realClient.listMyMemberships(),
-      listPersonEntities: () => realClient.entity.listByType("person"),
-      getEntity: async (uid: string) => {
-        try {
-          return await realClient.entity.get(uid);
-        } catch {
-          return null;
-        }
-      },
-    };
-
-    result = await pushAll(
-      {
-        hqRoot,
-        ...(onConflict ? { onConflict } : {}),
-        ...(message ? { message } : {}),
-        ...(skipPersonal ? { skipPersonal: true } : {}),
-      },
-      {
-        vaultClient: adapter,
-        share: (opts) =>
-          share({
-            paths: opts.paths,
-            company: opts.company,
-            vaultConfig,
-            hqRoot: opts.hqRoot,
-            ...(opts.onConflict ? { onConflict: opts.onConflict } : {}),
-            ...(opts.personalMode !== undefined
-              ? { personalMode: opts.personalMode }
-              : {}),
-            ...(opts.journalSlug !== undefined
-              ? { journalSlug: opts.journalSlug }
-              : {}),
-            ...(opts.message !== undefined ? { message: opts.message } : {}),
-            ...(opts.skipUnchanged !== undefined
-              ? { skipUnchanged: opts.skipUnchanged }
-              : {}),
-            ...(opts.propagateDeletes !== undefined
-              ? { propagateDeletes: opts.propagateDeletes }
-              : {}),
-            ...(opts.propagateDeletePolicy !== undefined
-              ? { propagateDeletePolicy: opts.propagateDeletePolicy }
-              : {}),
-            ...(author ? { author } : {}),
-          }),
-      },
-    );
-  } catch (err) {
-    console.error(
-      chalk.red("\n✗ Push-all failed:"),
-      err instanceof Error ? err.message : String(err),
-    );
-    process.exit(1);
-  }
-
-  for (const row of result.perCompany) {
-    if (row.error) {
-      console.log(chalk.red(`  ✗ ${row.slug}: ${row.error}`));
-    } else if (row.result) {
-      const r = row.result;
-      const status =
-        r.aborted || r.filesExcludedByScope > 0
-          ? chalk.yellow("⚠")
-          : chalk.green("✓");
-      console.log(
-        `  ${status} ${row.slug}: ${r.filesUploaded} file(s), ` +
-          `${formatBytes(r.bytesUploaded)}, ${r.filesSkipped} skipped, ` +
-          `${r.filesDeleted} deleted, ${r.filesExcludedByScope} scope-excluded, ` +
-          `${r.conflictPaths.length} conflict(s)` +
-          (r.aborted ? " — aborted" : ""),
-      );
-    }
-  }
-
-  const errored = result.errors.length;
-  const summary =
-    `\nPushed ${result.filesUploaded} file(s) ` +
-    `(${formatBytes(result.bytesUploaded)}) across ${result.attempted} ` +
-    `target(s); ${result.filesDeleted} deleted; ${errored} error(s); ` +
-    `${result.filesExcludedByScope} scope-excluded`;
-  console.log(
-    errored > 0 || result.filesExcludedByScope > 0
-      ? chalk.yellow(summary)
-      : chalk.green(summary),
-  );
-  if (result.filesExcludedByScope > 0) {
-    console.log(chalk.yellow(scopeExcludedWarning(result.filesExcludedByScope)!));
-  }
-  if (errored > 0) process.exit(1);
-}
-
-async function runNowSingle(
-  hqRoot: string,
-  company: string | undefined,
-  personal: boolean,
-  message?: string,
-  onConflict?: ConflictStrategy,
-  modeAllOverride?: boolean,
-  forceScopeShrink?: boolean,
-): Promise<void> {
-  console.log(chalk.bold("\nHQ Sync — Now"));
-  console.log(`  HQ root:  ${hqRoot}`);
-  console.log(`  Target:   ${personal ? "(personal)" : (company ?? "(active company)")}`);
-  console.log(`  Strategy: ${onConflict ?? "(interactive)"}\n`);
-
-  try {
-    const accessToken = await ensureCognitoToken();
-    const vaultConfig = buildVaultConfig(accessToken);
-    const author = resolveUploadAuthorFromCache();
-
-    // Resolve the target. For --personal, look up the canonical person and
-    // route paths/journal through personalMode. Otherwise use the company arg
-    // (or fall back to the active company inside share()/sync()).
-    let targetCompany = company;
-    let personalMode = false;
-    let journalSlug: string | undefined;
-    let pushPaths: string[];
-
-    if (personal) {
-      const client = new VaultClient(vaultConfig);
-      targetCompany = await resolveCanonicalPersonUid({
-        listMyMemberships: () => client.listMyMemberships(),
-        listPersonEntities: () => client.entity.listByType("person"),
-        getEntity: async () => null,
-      });
-      personalMode = true;
-      journalSlug = PERSONAL_VAULT_JOURNAL_SLUG;
-      pushPaths = computePersonalVaultPaths(hqRoot);
-    } else {
-      // For company targets we need a concrete slug to compute the push path.
-      // share() can resolve `company` itself for the upload, but the path
-      // computation must happen here. Use the explicit company if given;
-      // otherwise fall back to the active-company resolution inside the
-      // engine and compute paths from `hqRoot/companies` (share() will refuse
-      // anything outside that subtree anyway).
-      const slug = company ?? readActiveCompanySlug(hqRoot);
-      if (!slug) {
-        throw new Error(
-          "No company specified and no active company found. " +
-            "Use --company <slug>, --personal, or set up .hq/config.json.",
-        );
-      }
-      pushPaths = [path.join(hqRoot, "companies", slug)];
-    }
-
-    // Push first so the subsequent pull doesn't redownload files we were
-    // about to broadcast (matches hq-sync-runner ordering).
-    console.log(chalk.dim("  → push leg"));
-    const pushResult = await share({
-      paths: pushPaths,
-      company: targetCompany,
-      vaultConfig,
-      hqRoot,
-      skipUnchanged: true,
-      propagateDeletes: true,
-      propagateDeletePolicy: resolveDeletePolicy(),
-      ...(onConflict ? { onConflict } : {}),
-      ...(message ? { message } : {}),
-      ...(personalMode ? { personalMode: true } : {}),
-      ...(journalSlug !== undefined ? { journalSlug } : {}),
-      ...(author ? { author } : {}),
-    });
-    const pushStatus =
-      pushResult.aborted || pushResult.filesExcludedByScope > 0
-        ? chalk.yellow("⚠")
-        : chalk.green("✓");
-    console.log(
-      `    ${pushStatus} ` +
-        `${pushResult.filesUploaded} uploaded, ${pushResult.filesSkipped} skipped, ` +
-        `${pushResult.filesDeleted} deleted, ${pushResult.filesExcludedByScope} scope-excluded` +
-        (pushResult.aborted ? " — aborted" : ""),
-    );
-    if (pushResult.filesExcludedByScope > 0) {
-      console.log(chalk.yellow(scopeExcludedWarning(pushResult.filesExcludedByScope)!));
-    }
-    if (pushResult.aborted) {
-      console.log(chalk.yellow("\n⚠ Sync now aborted on push leg; pull skipped."));
-      process.exit(1);
-    }
-
-    // US-011: resolve membership sync-config so we can either nudge an
-    // all-mode owner or refuse the pull when strict-mode is on. Skipped
-    // for personal targets (personal vault has no membership row) and
-    // for resolution failures (best-effort — never block sync). The
-    // lookup runs BEFORE the pull leg so strict refusal can short-circuit
-    // without burning a sync.
-    const narrowHintLevel: BannerLevel = resolveBannerLevel();
-    let resolvedMode: MembershipSyncConfig["syncMode"] | undefined;
-    let resolvedCompanyUid: string | undefined;
-    if (!personalMode && targetCompany) {
-      try {
-        const client = new VaultClient(vaultConfig);
-        const memberships = await client.listMyMemberships();
-        const match = memberships.find(
-          (m) => m.companyUid === targetCompany || m.membershipKey === targetCompany,
-        );
-        if (match) {
-          resolvedCompanyUid = match.companyUid;
-          try {
-            const cfg = await client.getMembershipSyncConfig(
-              match.membershipKey,
-            );
-            resolvedMode = cfg.syncMode;
-          } catch {
-            resolvedMode = undefined;
-          }
-        }
-      } catch {
-        resolvedMode = undefined;
-      }
-    }
-
-    if (
-      resolvedMode === "all" &&
-      isStrictRefusal(resolvedMode, narrowHintLevel) &&
-      !modeAllOverride &&
-      resolvedCompanyUid
-    ) {
-      emitNarrowHint({
-        companyUid: resolvedCompanyUid,
-        syncMode: resolvedMode,
-        level: narrowHintLevel,
-      });
-      console.error(
-        chalk.red(
-          "\n✗ Sync now refused: strict narrow-hint mode is on and this " +
-            "membership still pulls everything. Run `hq sync narrow --apply` " +
-            "to migrate, or re-run with --mode-all.",
-        ),
-      );
-      process.exit(1);
-    }
-
-    // DEV-1768: resolve the membership's real scope and thread it into the
-    // pull leg, so `hq sync now` stops seeding all-mode PullRecords. Personal
-    // targets have no membership scope — they stay full ("all").
-    let pullScope: PullScope | undefined;
-    if (!personalMode) {
-      try {
-        pullScope = await resolveCliPullScope(
-          new VaultClient(vaultConfig),
-          targetCompany,
-          hqRoot,
-        );
-      } catch {
-        pullScope = undefined;
-      }
-    }
-
-    console.log(chalk.dim("  → pull leg"));
-    const excludePrefixes = readScopeExcludePrefixes(pullScope);
-    const pullResult = await sync({
-      company: targetCompany,
-      vaultConfig,
-      hqRoot,
-      ...(onConflict ? { onConflict } : {}),
-      ...(personalMode ? { personalMode: true } : {}),
-      ...(journalSlug !== undefined ? { journalSlug } : {}),
-      ...(pullScope?.syncMode !== undefined
-        ? { syncMode: pullScope.syncMode }
-        : {}),
-      ...(pullScope?.prefixSet !== undefined
-        ? { prefixSet: pullScope.prefixSet }
-        : {}),
-      // Sessions-exclusion: honor the resolver's excludePrefixes on the
-      // `hq sync now` pull leg too.
-      ...(excludePrefixes ? { excludePrefixes } : {}),
-      ...(forceScopeShrink ? { forceScopeShrink: true } : {}),
-    });
-    console.log(
-      `    ${pullResult.aborted ? chalk.yellow("⚠") : chalk.green("✓")} ` +
-        `${pullResult.filesDownloaded} downloaded, ${pullResult.filesSkipped} skipped, ` +
-        `${pullResult.conflicts} conflict(s)` +
-        (pullResult.aborted ? " — aborted" : ""),
-    );
-
-    if (pullResult.aborted) {
-      console.log(chalk.yellow("\n⚠ Sync now finished with pull leg aborted."));
-      process.exit(1);
-    }
-
-    // US-011: emit the hint banner after a successful pull so it
-    // appears at the bottom of the summary rather than mid-stream.
-    if (resolvedMode === "all" && resolvedCompanyUid) {
-      emitNarrowHint({
-        companyUid: resolvedCompanyUid,
-        syncMode: resolvedMode,
-        level: narrowHintLevel,
-      });
-    }
-
-    console.log(chalk.green("\n✓ Sync now complete"));
-  } catch (err) {
-    console.error(
-      chalk.red("\n✗ Sync now failed:"),
-      err instanceof Error ? err.message : String(err),
-    );
-    process.exit(1);
-  }
-}
-
-async function runNowAll(
-  hqRoot: string,
-  message?: string,
-  onConflict?: ConflictStrategy,
-  modeAllOverride?: boolean,
-  skipPersonal?: boolean,
-  forceScopeShrink?: boolean,
-): Promise<void> {
-  console.log(chalk.bold("\nHQ Sync — Now (all)"));
-  console.log(`  HQ root:  ${hqRoot}`);
-  console.log(`  Strategy: ${onConflict ?? "(interactive)"}`);
-  if (skipPersonal) {
-    console.log(`  Personal: skipped (--no-personal)`);
-  }
-  console.log("");
-
-  // Push first (matches runner), then pull. Re-uses the per-leg orchestrators
-  // so the per-target rendering, error isolation, and exit codes are
-  // identical to running `push --all` then `pull --all` back-to-back.
-  console.log(chalk.dim("→ push --all"));
-  await runPushAll(hqRoot, message, onConflict, skipPersonal);
-  console.log(chalk.dim("\n→ pull --all"));
-  // US-011: forward --mode-all so the strict refusal applies to the
-  // pull leg (push doesn't need a narrow-hint — the narrow ritual is
-  // pull-side).
-  await runPullAll(
-    hqRoot,
-    onConflict,
-    modeAllOverride,
-    skipPersonal,
-    forceScopeShrink,
-  );
-}
-
-/**
- * Best-effort read of the active company slug from `<hqRoot>/.hq/config.json`.
- * Returns undefined when the file is missing, malformed, or has no
- * `activeCompany` field — `runNowSingle` surfaces a clean error in that case.
- */
-function readActiveCompanySlug(hqRoot: string): string | undefined {
-  const configPath = path.join(hqRoot, ".hq", "config.json");
-  if (!fs.existsSync(configPath)) return undefined;
-  try {
-    const cfg = JSON.parse(fs.readFileSync(configPath, "utf-8")) as {
-      activeCompany?: string;
-    };
-    return cfg.activeCompany;
-  } catch {
-    return undefined;
-  }
-}
-
-/**
- * Human-friendly label for a journal slug in `hq sync status`. The
- * personal-vault fanout slot and the legacy `companies/personal` company both
- * carry opaque slugs; everything else is a real company slug shown as-is.
- */
-function scopeLabel(slug: string): string {
-  if (slug === PERSONAL_VAULT_JOURNAL_SLUG) return "personal vault";
-  if (slug === "personal") return "personal (companies/personal)";
-  return slug;
-}
-
-function formatBytes(bytes: number): string {
-  if (bytes === 0) return "0 B";
-  const units = ["B", "KB", "MB", "GB"];
-  const exponent = Math.min(
-    Math.floor(Math.log(bytes) / Math.log(1024)),
-    units.length - 1,
-  );
-  const value = bytes / Math.pow(1024, exponent);
-  return `${value.toFixed(value >= 100 || exponent === 0 ? 0 : 1)} ${units[exponent]}`;
-}
-
-/**
- * Read all of stdin as a UTF-8 string. Used by `--creds-from-stdin` to
- * receive a JSON-serialized EntityContext from the parent process (e.g.
- * AppBar HQ Sync). Returns the empty string when stdin closes immediately.
- *
- * Caller is expected to detect TTY first — this function will block forever
- * waiting for stdin to close if invoked interactively.
- */
-async function readAllStdin(): Promise<string> {
-  const chunks: Buffer[] = [];
-  for await (const chunk of process.stdin) {
-    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-  }
-  return Buffer.concat(chunks).toString("utf8");
-}
-
-/**
- * Resolve the syncing user's `UploadAuthor` (sub + email) from the cached
- * Cognito idToken. Returns `undefined` when no tokens are cached or the
- * token is missing the required claims — share() then skips the metadata
- * stamp gracefully (not an error).
- *
- * We deliberately decode the JWT here instead of verifying it: Cognito
- * already verified at issuance, and we only use the public claims to
- * label the upload's S3 user metadata (no auth decision rides on it).
- */
-function resolveUploadAuthorFromCache(): UploadAuthor | undefined {
-  const tokens = loadCachedTokens();
-  if (!tokens?.idToken) return undefined;
-  const parts = tokens.idToken.split(".");
-  if (parts.length !== 3) return undefined;
-  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");
-    const claims = JSON.parse(json) as { sub?: string; email?: string };
-    if (claims.sub && claims.email) {
-      return { userSub: claims.sub, email: claims.email };
-    }
-    return undefined;
-  } catch {
-    return undefined;
-  }
-}