@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/cli/sync.ts

@@ -1,3470 +0,0 @@
-/**
- * `hq sync` command — pull everything allowed from entity vault (VLT-5 US-002).
- *
- * Pulls all files the caller's STS session policy permits.
- * Never auto-overwrites local changes — prompts on conflict.
- */
-
-import * as fs from "fs";
-import * as path from "path";
-import type {
-  EntityContext,
-  VaultServiceConfig,
-  SyncJournal,
-} from "../types.js";
-import { VaultAuthError, VaultClient, type SyncMode } from "../vault-client.js";
-import { readlinkOrNull } from "../lib/readlink-safe.js";
-import {
-  emitCloudTelemetry,
-  type TelemetryClaims,
-} from "../telemetry-events.js";
-import { resolveEntityContext, isExpiringSoon, refreshEntityContext } from "../context.js";
-import { createSyncProgressRecorder } from "../sync-progress.js";
-import {
-  canonicalVaultKeySpelling,
-  localPathForVaultKey,
-  vaultKeyForLocalPath,
-} from "../local-path-codec.js";
-import { SKILLS_KEY_PREFIX } from "./doctor.js";
-import {
-  downloadFile,
-  listRemoteFiles,
-  headRemoteFile,
-  primeObjectTransport,
-  toPosixKey,
-  classifyVaultKey,
-  DanglingSymlinkParentError,
-} from "../s3.js";
-import type { DownloadModeWarning, RemoteFile } from "../s3.js";
-import {
-  readJournal,
-  writeJournal,
-  hashFile,
-  hashSymlinkTarget,
-  updateEntry,
-  removeEntry,
-  getEntry,
-  normalizeEtag,
-  migrateToV2,
-  gcTombstones,
-  isTombstone,
-  tombstoneEntry,
-  lastPullRecord,
-  appendPullRecord,
-  generatePullId,
-  PERSONAL_VAULT_JOURNAL_SLUG,
-  migratePersonalVaultJournal,
-} from "../journal.js";
-import {
-  isGeneratedCoreMirrorKey,
-  PERSONAL_VAULT_MANIFEST_KEY,
-} from "../personal-vault.js";
-import { isPersonalVaultExcluded } from "../personal-vault-exclusions.js";
-import {
-  buildScopeShrinkPlan,
-  applyScopeShrink,
-  ScopeShrinkBlockedError,
-  ScopeShrinkLargePruneError,
-  type ScopeShrinkAdviceContext,
-} from "../scope-shrink.js";
-import {
-  coalescePrefixes,
-  isCoveredByAny,
-  type ScopePrefixInput,
-} from "../prefix-coalesce.js";
-import { createIgnoreFilter } from "../ignore.js";
-import {
-  hasRemoteChanged,
-  isAccessDenied,
-  resolveActiveCompany,
-  resolveTransferConcurrency,
-} from "../sync-core.js";
-import { isEphemeralPath, isForbiddenCompanyVaultKey, isMalformedVaultKey } from "./share.js";
-import { resolveConflict } from "./conflict.js";
-import type { ConflictStrategy, ConflictResolution } from "./conflict.js";
-import {
-  buildConflictId,
-  buildConflictPath,
-  readShortMachineId,
-} from "../lib/conflict-file.js";
-import { appendConflictEntry } from "../lib/conflict-index.js";
-import { isCloudAuthoritative } from "../lib/cloud-authoritative.js";
-import { reindex } from "./reindex.js";
-import { withOperationLock } from "../operation-lock.js";
-import {
-  fetchCompanyTombstones,
-  type CompanyTombstone,
-} from "./tombstones.js";
-
-/**
- * Per-file events emitted by `sync()` as it progresses.
- *
- * When `SyncOptions.onEvent` is set, these events are delivered to the caller
- * in place of the default human-readable `console.log` / `console.error`
- * output. This is the seam that lets `hq-sync-runner` stream ndjson to the
- * AppBar menubar without the engine knowing anything about ndjson (ADR-0001).
- *
- * The human CLI (`hq sync`) leaves `onEvent` undefined and falls through to
- * `defaultConsoleLogger` below, which preserves the existing tty output.
- *
- * A single `plan` event is emitted once at the start of every run, before
- * any `progress`/`conflict`/`error` events. It carries the totals derived
- * from a Stage-1 classification pass so consumers can render an accurate
- * progress denominator before transfers begin (the menubar's "Preparing
- * sync…" pre-pass becomes obsolete once the runner forwards this).
- */
-export type SyncProgressEvent =
-  | {
-      type: "plan";
-      /** Files this run intends to download (pull-only; 0 from share). */
-      filesToDownload: number;
-      bytesToDownload: number;
-      /** Files this run intends to upload (push-only; 0 from sync). */
-      filesToUpload: number;
-      bytesToUpload: number;
-      /** Files classified as no-op (ignored, unchanged, local-only on pull). */
-      filesToSkip: number;
-      /**
-       * Files known up-front to be conflicts. Pull-side fills this from the
-       * 3-way merge against the journal; push-side leaves it 0 because
-       * conflict detection requires a remote HEAD that runs in Stage 2.
-       */
-      filesToConflict: number;
-      /**
-       * Remote keys this run intends to delete from S3 (push-only with
-       * `propagateDeletes`; 0 from sync). A key is scheduled for deletion when
-       * its journal entry exists, the local file is gone, and the key falls
-       * within the share scope. The bucket has versioning enabled so the
-       * delete is soft (a delete-marker is written; prior versions remain
-       * recoverable).
-       */
-      filesToDelete: number;
-    }
-  | {
-      type: "progress";
-      path: string;
-      bytes: number;
-      message?: string;
-      /** True when this event reports a remote DeleteObject (no upload). */
-      deleted?: boolean;
-      /**
-       * Transfer direction for this file, stamped by the runner's per-company
-       * tagger from the in-flight phase: `"up"` for a push (local→S3 upload),
-       * `"down"` for a pull (S3→local download). Optional because the inner
-       * `share()`/`sync()` emitters don't know the run-level phase — only the
-       * runner's `tagAndEmit` does, and it sets this when re-emitting to stdout.
-       * Consumers (the menubar activity log) use it to label each file
-       * uploaded vs downloaded.
-       */
-      direction?: "up" | "down";
-      /**
-       * Email of the file's author, read from the S3 object's `created-by`
-       * user-metadata. Only set on the download/pull path (a downloaded file
-       * was authored by whoever uploaded it); push-side progress has no author
-       * because the uploader is the local user. `null`/absent when the object
-       * carries no `created-by`. The menubar activity log shows this so the
-       * user sees who authored each file they received.
-       */
-      author?: string | null;
-    }
-  | { type: "error"; path: string; message: string }
-  | {
-      type: "conflict";
-      path: string;
-      direction: "pull" | "push";
-      resolution: ConflictResolution;
-    }
-  | {
-      /**
-       * Emitted when a planner-flagged pull conflict turned out to be a false
-       * positive: the remote bytes fetched for the conflict mirror hashed
-       * byte-for-byte identical to the local file, so there is nothing to
-       * resolve. The planner can only see journal-relative deltas (local hash
-       * != journal hash AND remote etag != journal etag), so a stale journal
-       * baseline makes identical content look like a both-sides change. Known
-       * stale-baseline triggers: a shared-journal cross-root collision (the
-       * personal vault + `companies/personal` sharing one journal), an
-       * mtime-rounding fast-path miss, KMS/multipart etag churn on a no-op
-       * re-upload, a second machine advancing S3 + its own journal, or a
-       * manual revert. The executor re-stamps the journal baseline (so neither
-       * side looks changed next run) and skips — no conflict counted, no
-       * `.conflict-*` mirror written. Counted as a skip; surfaced here purely
-       * for observability so a UI can explain why N "conflicts" silently
-       * resolved themselves.
-       */
-      type: "reconciled";
-      path: string;
-      direction: "pull" | "push";
-    }
-  | {
-      type: "new-files";
-      files: Array<{ path: string; bytes: number; addedBy: string | null }>;
-    }
-  | {
-      /**
-       * Emitted by the `currency-gated` delete policy when a delete candidate
-       * is refused. Two reasons, discriminated by `reason`:
-       *
-       *   - `"stale-etag"`: the local file is missing but the remote object's
-       *     current ETag no longer matches the journal's last-recorded etag.
-       *     Some other device (or another out-of-band write) modified the
-       *     remote object since this machine last synced it. The pull leg of
-       *     `sync now` will re-pull naturally via the same `hasRemoteChanged`
-       *     path that powers conflict detection. Journal entry is left intact
-       *     so the pull can use it as the baseline for the 3-way merge.
-       *     `journalEtag` and `remoteEtag` are real ETag strings.
-       *
-       *   - `"legacy-no-etag"`: the journal entry predates remoteEtag tracking
-       *     (no `remoteEtag` recorded). We can't prove currency without an
-       *     etag, so the delete is refused in the safe direction. A future
-       *     sync that picks up an etag for this entry can re-evaluate.
-       *     `journalEtag` and `remoteEtag` are sentinel strings
-       *     (`<legacy-no-etag>` / `<unknown>`) — do not render as ETags.
-       *     Consumers should branch on `reason`, not on the etag values.
-       *
-       *   - `"bulk-asymmetry"`: the bulk-asymmetry circuit-breaker tripped
-       *     (see `delete-refused-bulk-asymmetry`). Each candidate that would
-       *     have been deleted also surfaces here for path-level visibility.
-       *     `journalEtag` and `remoteEtag` are sentinel strings
-       *     (`<bulk-asymmetry>` / `<not-checked>`) since no HEAD was issued.
-       */
-      type: "delete-refused-stale-etag";
-      path: string;
-      journalEtag: string;
-      remoteEtag: string;
-      reason:
-        | "stale-etag"
-        | "legacy-no-etag"
-        | "bulk-asymmetry"
-        | "divergent-local"
-        | "missing-delete-intent"
-        | "intent-changed"
-        | "recreated-locally";
-    }
-  | {
-      /**
-       * Emitted at most ONCE per `share()` call when the bulk-asymmetry
-       * circuit-breaker tripped: a large fraction of the in-scope journal
-       * entries are missing locally, suggesting the local mirror is corrupt
-       * (moved hqRoot, partial restore, fresh clone over inherited state,
-       * unmounted volume, accidental `rm -rf`) rather than a deliberate
-       * delete. The engine refuses to convert the missing entries into
-       * remote `DeleteObject` calls; every refused candidate also surfaces
-       * via `delete-refused-stale-etag` with `reason: "bulk-asymmetry"`.
-       *
-       * Trip condition: `candidates >= 10 AND candidates / inScope >= 0.10`.
-       * Bypass: set `HQ_SYNC_DELETE_BULK_OVERRIDE=1` (truthy: `1|true|yes`,
-       * case-insensitive) OR pass `propagateDeletePolicy: "all"` (the
-       * existing emergency-reconcile policy which already opts out of
-       * safety gates).
-       *
-       * `candidates` is the number of journal entries whose local file is
-       * missing AND would have been delete-candidates absent the guard;
-       * `inScope` is the total journal entries under the share's scope
-       * roots; `ratio = candidates / inScope`; `samplePaths` carries up to
-       * 10 refused keys for diagnostic display.
-       */
-      type: "delete-refused-bulk-asymmetry";
-      candidates: number;
-      inScope: number;
-      ratio: number;
-      samplePaths: string[];
-    }
-  | {
-      /**
-       * Emitted at most ONCE per `share()` call (push leg of a sync run) when
-       * `personalMode === true` and the personal-vault default-exclusion list
-       * blocked one or more files that would otherwise have uploaded. Gives
-       * the UI a single summary signal — "N files quietly excluded by default
-       * policy" — without firing one event per excluded file (which would
-       * dominate the event stream on first-sync of a dirty tree).
-       *
-       * `count` is the total number of paths the exclusion filter rejected
-       * (deduplicated across the walk). `samplePaths` carries up to 10
-       * forward-slash-separated relative paths for diagnostic display. `byId`
-       * is a per-exclusion-rule breakdown so the UI can render which class
-       * of exclusion did the work (secret / machine-local / scratch / …).
-       *
-       * Not emitted when `count === 0` — silent on a clean tree.
-       */
-      type: "personal-vault-out-of-policy";
-      count: number;
-      samplePaths: string[];
-      byId: Record<string, number>;
-    }
-  | {
-      /**
-       * Emitted at most ONCE per `share()` call (push leg) when the run is
-       * scoped to a member/guest's ACL prefixes (`prefixSet`) and one or more
-       * candidate paths fell OUTSIDE the granted prefixes. Those paths are
-       * skipped from the upload (and delete) plan instead of being PUT — the
-       * vended child credential is scoped to the granted prefixes, so pushing
-       * them would draw the server's correct 403 `SCOPE_EXCEEDS_PARENT` and
-       * (pre-fix) abort the WHOLE company. This is the push-side analogue of
-       * the pull-side `skip-out-of-scope` action.
-       *
-       * `count` is the number of distinct company-relative paths/prefixes the
-       * scope filter excluded; `samplePaths` carries up to 10 for diagnostic
-       * display. Informational, NOT an error — the company still syncs its
-       * in-scope subset and the run exits 0.
-       *
-       * Not emitted when `count === 0` — silent on a fully in-scope tree.
-       */
-      type: "scope-excluded";
-      count: number;
-      samplePaths: string[];
-    }
-  | {
-      /**
-       * Emitted at most ONCE per PULL leg when the leg ran under a
-       * membership-scoped `syncMode` (`"shared"` or `"custom"` — never `"all"`)
-       * AND one or more remote keys were withheld BY THAT MEMBERSHIP SCOPE
-       * (`skip-out-of-scope` with `reason: "membership-scope"`). This turns the
-       * silent shared-vs-all gap into a
-       * VISIBLE, actionable surface. The reporter of feedback_d2082110 lost
-       * files across devices precisely because four memberships defaulted to
-       * `shared` rather than `all`, so not all vault content materialized on the
-       * second device — and nothing told them; they had to notice the gap and
-       * flip each membership to `all` by hand. This event names the gap and the
-       * lever (raise the membership's access level to `all`) so FULL
-       * materialization is a deliberate, visible choice rather than a silent
-       * omission.
-       *
-       * `count` is the number of remote keys the MEMBERSHIP SCOPE withheld on
-       * this leg; `samplePaths` carries up to 10 company-relative keys for
-       * display; `syncMode` is the active scoped mode. Push-only keys
-       * (`sessions/`, US-006) are deliberately EXCLUDED from both — they are
-       * withheld in every mode including `all`, so the lever this event names
-       * would not materialize them. `count` is therefore ≤
-       * `SyncResult.filesOutOfScope`, which keeps its both-causes meaning.
-       * Distinct from the push-side `scope-excluded` (which reports what a
-       * grantee could not PUSH). Not emitted in `all` mode or when nothing was
-       * withheld by the membership scope — no gap, no noise.
-       */
-      type: "scope-materialization-gap";
-      count: number;
-      samplePaths: string[];
-      syncMode: SyncMode;
-    }
-  | {
-      /**
-       * Emitted at most ONCE per `share()` push leg when the base ignore
-       * filter dropped one or more NOTEWORTHY paths: content that does not
-       * match expected build/VCS/cache noise classes. Surfaces an over-broad
-       * exclusion that would otherwise drop content silently (DEV-1791).
-       *
-       * `count` is the number of distinct noteworthy paths; `totalExcluded`
-       * is all base-ignore rejections including expected noise; `samplePaths`
-       * carries up to 10 noteworthy paths. Not emitted when `count === 0`.
-       */
-      type: "ignore-excluded";
-      count: number;
-      totalExcluded: number;
-      samplePaths: string[];
-    }
-  | {
-      /**
-       * Emitted by the PUSH leg (`share()`) once per key whose upload was
-       * suppressed because an authoritative FILE_TOMBSTONE marks it deleted and
-       * the local copy is still the deleted baseline (journal hash unchanged).
-       * Without this, a behind peer that still holds the file would re-upload it,
-       * and the pull planner's timestamp-only re-create heuristic
-       * (`isRemoteRecreateAfterTombstone`) would treat the re-upload as a genuine
-       * re-create and resurrect the key for everyone. The deleter's own stale
-       * local copy is cleaned by the pull leg's `tombstone-delete`; this event
-       * records that the push refused to resurrect it. `deletedAt` is the
-       * tombstone's delete time.
-       */
-      type: "upload-suppressed-tombstone";
-      path: string;
-      deletedAt: string;
-    }
-  | {
-      /**
-       * Emitted by the PUSH leg (`share()`) once per local file skipped because
-       * it exceeds the max sync size (`isWithinSizeLimit`, 50 MB default). This
-       * is a permanent, benign, user-policy outcome — the file is too big to
-       * sync and will be over the cap on every pass — so it is NOT an error and
-       * the run exits 0. It was previously emitted as `type: "error"`, which
-       * pushed it into the runner's `errors[]` and made every watch pass return
-       * exit 2; the menubar supervisor then reported that as
-       * "auto-sync watcher exited unexpectedly (code=Some(2))" on every tick —
-       * the HQ-SYNC-4 flood across user machines. Surfaced here purely for visibility
-       * (`bytes` is the offending file's size) so a UI/CLI can tell the user
-       * which file was too big without treating it as a failure.
-       */
-      type: "skip-size-limit";
-      path: string;
-      bytes: number;
-    }
-  | {
-      /**
-       * Emitted once per key skipped because it is permanently unstorable.
-       *
-       * PULL leg: a remote key the server will never presign (for example, a
-       * `companies/…`-prefixed key in a company-scoped vault or a key with
-       * control characters) — bucket poisoning from an outdated direct-S3
-       * client. PUSH leg: a local key the upload validator would reject, so
-       * the upload can only ever throw — a doubled-tree `companies/…` key, or
-       * a control-character path such as a macOS Finder `Icon\r` file. Like
-       * `skip-size-limit`, this is deliberately NOT `type: "error"` — one bad
-       * object must never error a whole company sync (erroring gated
-       * heartbeat toolset refreshes fleet-wide in the incident). Surfaced for
-       * visibility + cloud telemetry; per policy
-       * hq-alert-baseline-calibration the healthy baseline is ZERO such keys,
-       * so any occurrence is signal.
-       */
-      type: "skip-invalid-scoped-key";
-      path: string;
-      /** Server-compatible invalid-key code, such as INVALID_KEY_CONTROL_CHARS. */
-      errorCode?: string;
-    }
-  | {
-      /**
-       * Emitted by the PULL leg once per remote key skipped because its
-       * spelling percent-decodes to the same logical path as an
-       * already-journaled key with a DIFFERENT spelling — the mixed-version
-       * amplifier (a pre-codec peer minting `%3A`/`%253A` twins of a
-       * canonical `:` key). Downloading the twin would materialize a junk
-       * local dir and fork the journal into a second key family for one
-       * logical path, so the established spelling wins and the twin is
-       * skipped. Like `skip-size-limit`, this is deliberately NOT
-       * `type: "error"` (policy hq-sync-deliberate-skip-not-fatal-error-exit2:
-       * a recurring benign per-file skip emitted as an error lands in the
-       * runner's `errors[]`, forces exit 2 on every pass, and the menubar
-       * Sentry-alerts each time). The US-003 vault doctor is the cleanup
-       * path that collapses the junk family itself.
-       */
-      type: "skip-junk-key-spelling";
-      path: string;
-      /** The already-journaled spelling that owns this logical path. */
-      journaledKey: string;
-    }
-  | {
-      /**
-       * Emitted when local content is deliberately not transferred and would
-       * otherwise vanish from sync output without a trace (feedback_258e4a86 /
-       * feedback_a51cb63d — an hour lost because a "Pushed 0 file(s)" success
-       * named nothing that was skipped). Push batches by reason; pull emits an
-       * unreadable link by its remote key. `reason` distinguishes the cause:
-       *
-       *   - `"unreachable-path"`: a path the caller EXPLICITLY named exists on
-       *     disk but the resolver could not place it under the company folder,
-       *     or could not find it under any base. This is actionable signal — the
-       *     named target was NOT shipped — so the CLI may treat it as an error.
-       *   - `"linked-subtree"`: a directory symlink whose target lives OUTSIDE
-       *     the company folder was recorded as a link but its contents were not
-       *     descended/uploaded. They sync via their own repo, not the vault;
-       *     this is informational, not an error.
-       *   - `"unreadable-link"`: the OS identified a local symbolic link but
-       *     did not expose a readable target. The link is skipped rather than
-       *     dereferenced, and the company leg remains complete.
-       *
-       * `count` is the number of distinct paths for that reason; `samplePaths`
-       * carries up to 10 for display. Not emitted when `count === 0`.
-       */
-      type: "not-shipped";
-      reason: "unreachable-path" | "unreadable-link" | "linked-subtree";
-      count: number;
-      samplePaths: string[];
-    };
-
-export interface SyncOptions {
-  /** Company slug or UID (defaults to active company from config) */
-  company?: string;
-  /** Non-interactive conflict strategy */
-  onConflict?: ConflictStrategy;
-  /** Vault service config */
-  vaultConfig: VaultServiceConfig;
-  /** HQ root directory */
-  hqRoot: string;
-  /**
-   * Per-file event callback. When present, suppresses the default
-   * `console.log`/`console.error` human output — the caller is expected to
-   * render events themselves (e.g. emit ndjson to stdout). When absent, the
-   * default human logger is used. See `SyncProgressEvent`.
-   */
-  onEvent?: (event: SyncProgressEvent) => void;
-  /**
-   * When true, the caller is syncing against the caller's person-entity
-   * bucket. Pulled keys whose path starts with `companies/` are local
-   * (non-cloud) companies that sync to the personal vault by default —
-   * they are allowed through EXCEPT for slugs in `teamSyncedSlugs` (which
-   * are cloud-backed orphans, see below). `companies/manifest.yaml` is
-   * always allowed (routing source-of-truth).
-   */
-  personalMode?: boolean;
-  /**
-   * Slugs of companies the operator has an active team-bucket Membership
-   * for. Only consulted when `personalMode === true`: keys under
-   * `companies/{slug}/...` for any slug in this set are dropped as orphans
-   * from a pre-promotion personal-bucket fallback (the company became
-   * cloud-true). The push-side decommission cycle removes these from the
-   * bucket; this filter prevents them from re-downloading into the same
-   * disk paths the team-bucket pull manages.
-   */
-  teamSyncedSlugs?: ReadonlySet<string>;
-  /**
-   * Override for the per-slug journal file name. Defaults to `ctx.slug`.
-   * sync-runner passes `journalSlug: "personal"` for the personal slot so
-   * TS runner and Rust first-push share idempotency state.
-   */
-  journalSlug?: string;
-  /**
-   * Effective sync mode for this leg (US-005 wiring). Defaults to `"all"`
-   * when absent, preserving the legacy full-bucket pull. The runner resolves
-   * this from the membership's sync-config (`getMembershipSyncConfig`).
-   *
-   * SECURITY NOTE: this is a footprint/UX filter, NOT an authorization
-   * boundary. The security boundary is the server (STS credential scope +
-   * ACL). An owner's STS is wide (role-bypass), so this client-side scope is
-   * what makes selective download durable for owners — but it never grants
-   * access beyond what STS already permits.
-   */
-  syncMode?: SyncMode;
-  /**
-   * Coalesced, COMPANY-RELATIVE prefixes the current pull is scoped to when
-   * `syncMode` is `"shared"` or `"custom"` (same namespace as `RemoteFile.key`
-   * and the per-slug journal keys — e.g. `"knowledge/"`, `"projects/x/"`).
-   * Ignored when `syncMode` is `"all"`. The runner derives this from the
-   * caller's explicit grants (`shared`) or `customPaths` (`custom`) and is
-   * responsible for normalizing into the company-relative namespace.
-   *
-   * A `shared` leg with an empty/undefined `prefixSet` means "nothing is
-   * shared with me" → download nothing. The runner MUST fall back to `"all"`
-   * (not empty `"shared"`) on any grant-resolution error, so a transient
-   * failure can never silently prune the local tree.
-   */
-  prefixSet?: ScopePrefixInput[];
-  /**
-   * Company-relative prefixes SUBTRACTED from the effective pull scope in EVERY
-   * mode — the push-only set (US-006). Carries `sessions/`: session transcripts
-   * are pushed into the vault but never auto-pulled onto grantee laptops, even
-   * under `syncMode: "all"` (which otherwise pulls the whole bucket). A remote
-   * key downloads iff it is covered by the inclusion scope (`prefixSet`, or all
-   * of `all` mode) AND NOT covered by any `excludePrefixes` entry; excluded
-   * keys are classified `skip-out-of-scope`.
-   *
-   * CRITICAL: this set is applied ONLY to the download filter. It is
-   * deliberately NOT fed into the scope-shrink pass (which keeps using the
-   * inclusion `prefixSet` + pins), so a locally-authored (`direction:"up"`) or
-   * pinned on-demand-materialized session is NEVER orphaned/pruned — it is
-   * merely not re-pulled. The runner derives this from
-   * `resolvePullScope().excludePrefixes`.
-   */
-  excludePrefixes?: ScopePrefixInput[];
-  /**
-   * When the effective scope shrinks relative to the last pull and the shrink
-   * would orphan locally-modified ("dirty") files, `sync()` aborts with a
-   * `ScopeShrinkBlockedError` by default. Set `true` to proceed anyway:
-   * dirty files are LEFT ON DISK and only their journal entries are
-   * tombstoned. Mirrors `hq sync narrow --force`.
-   */
-  forceScopeShrink?: boolean;
-  /**
-   * How `sync()` handles a scope shrink (US-005 / DEV-1768):
-   *
-   *   - `"block"` (default) — a human is present (foreground `hq sync`). Dirty
-   *     out-of-scope orphans, or a clean prune over the safety cap, raise a
-   *     structured error whose advice is followable from a terminal. Clean
-   *     orphans within the cap are QUARANTINED (moved, not deleted).
-   *   - `"auto-recover"` — the background menubar runner, which can take no
-   *     interactive flag. NEVER throws on a shrink: dirty orphans are kept on
-   *     disk + un-tracked, clean orphans are quarantined, and the bulk-prune
-   *     cap is bypassed (quarantine is non-destructive). This is what clears an
-   *     already-wedged journal on the next sync, idempotently and without data
-   *     loss — the recovery seam for the all→shared seed bug.
-   *
-   * Both policies are non-destructive for CLEAN files (quarantine, never
-   * silent delete) — the deliberate `hq sync narrow --apply` ritual is the only
-   * path that hard-deletes, and it confirms first.
-   */
-  scopeShrinkPolicy?: "block" | "auto-recover";
-  /**
-   * The caller's own Cognito `sub`, used by the scope-shrink authorship guard
-   * so a scope shrink never prunes content the caller authored. Injected by the
-   * entry point — the runner sources it from its decoded idToken claims (the
-   * same sub stamped onto uploads as `created-by-sub`). The engine never reads
-   * it from disk, so it stays pure/hermetic; undefined degrades safely.
-   */
-  callerSub?: string;
-  /**
-   * Optional decoded Cognito claims used only for action telemetry attribution
-   * (agentUid when `custom:entityType=agent`). Sync behavior never branches on
-   * this field.
-   */
-  telemetryClaims?: TelemetryClaims | null;
-  /**
-   * Skip the post-sync `reindex()` refresh (skill wrappers + personal overlay
-   * mirrors + workers registry). By default, when a sync changes on-disk
-   * sources (downloads, tombstones, or scope-orphan removals), `sync()`
-   * re-runs reindex so the generated `.claude/skills/<ns>:<skill>` wrappers
-   * stay in sync. An orchestrator syncing many companies in one pass can set
-   * this and run `reindex()` once itself instead of per-company.
-   */
-  skipReindex?: boolean;
-  /**
-   * Internal runner seam: true only when the caller already holds the
-   * per-root operation lock for this sync pass.
-   */
-  operationLockAlreadyHeld?: boolean;
-}
-
-export interface SyncResult {
-  filesDownloaded: number;
-  bytesDownloaded: number;
-  filesSkipped: number;
-  conflicts: number;
-  /**
-   * Paths (remote keys) that were detected as conflicts during this run.
-   * Always populated when `conflicts > 0` so callers can surface them in UI
-   * or logs without re-streaming the per-file events.
-   */
-  conflictPaths: string[];
-  aborted: boolean;
-  /**
-   * Files classified as "new" during pull — i.e. the remote file had no
-   * local counterpart at classification time. Additive field; empty array
-   * when no new files were detected or on push-only syncs.
-   */
-  newFiles: Array<{ path: string; bytes: number }>;
-  /** Convenience count: `newFiles.length`. */
-  newFilesCount: number;
-  /**
-   * Count of remote keys refused at planning time because they matched
-   * `EPHEMERAL_PATH_PATTERN` (conflict-mirror files that must never round-
-   * trip through the bucket). Mirrors `ShareResult.filesExcludedByPolicy`
-   * so push and pull report the same shape. Pre-fix this count was always
-   * 0 on the pull side and legacy `.conflict-*` litter rode every sync —
-   * see Bug #2 in workspace/reports/hq-cloud-5.33.0-deep-test.md.
-   */
-  filesExcludedByPolicy: number;
-  /**
-   * Count of journal-known keys applied as local deletes during this pull
-   * because the remote LIST no longer contains them — the cross-machine
-   * delete-propagation signal that Bug #9 closes. The peer's push leg
-   * removed the object from S3 (`hq sync` push side verified-to-work in
-   * the deep-test addendum), but pre-fix the pull side never enumerated
-   * "what's missing-from-remote-that-was-there-before", so the file
-   * lingered locally forever. Always 0 when no journal-known keys have
-   * disappeared from the remote.
-   */
-  filesTombstoned: number;
-  /**
-   * Count of remote keys NOT downloaded this run because they fall outside
-   * the effective `syncMode` scope (US-005). Always 0 in `all` mode. Distinct
-   * from `filesSkipped` (which measures "unchanged on this run") so consumers
-   * can render a "N outside your sync scope" line. The matching local cleanup
-   * of previously-downloaded-now-out-of-scope files is reported via
-   * `scopeOrphansRemoved`.
-   */
-  filesOutOfScope: number;
-  /**
-   * Clean local orphans deleted this run because a scope shrink moved them
-   * outside the effective scope (US-005). 0 when scope did not shrink.
-   */
-  scopeOrphansRemoved: number;
-  /**
-   * Dirty (locally-modified) orphans that a scope shrink would have pruned.
-   * When `forceScopeShrink` is false these are surfaced via a thrown
-   * `ScopeShrinkBlockedError` and the leg never reaches this result; when
-   * true they are left on disk and tombstoned, and counted here.
-   */
-  scopeOrphansBlocked: number;
-  /**
-   * Remote keys whose local on-disk counterpart changed during this pull.
-   * Includes downloads, tombstone deletes, and clean scope-orphan removals.
-   */
-  changedPaths?: string[];
-}
-
-type SyncEventEmitter = (event: SyncProgressEvent) => void;
-
-type PullDownloadItem = Extract<PullPlanItem, { action: "download" }>;
-
-interface PullRunContext {
-  options: SyncOptions;
-  companyRef: string;
-  vaultConfig: VaultServiceConfig;
-  hqRoot: string;
-  emit: SyncEventEmitter;
-  ctx: EntityContext;
-  companyRoot: string;
-  shouldSync: (filePath: string, isDir?: boolean) => boolean;
-  journalSlug: string;
-  startedAt: string;
-  journal: SyncJournal;
-  remoteFiles: RemoteFile[];
-  syncMode: SyncMode;
-  currentPrefixSet: string[];
-  /**
-   * Coalesced push-only exclusion prefixes (US-006: `sessions/`), subtracted
-   * from the download filter in EVERY mode. Kept SEPARATE from
-   * `currentPrefixSet` on purpose: the scope-shrink pass reads only
-   * `currentPrefixSet` (+ pins), so excluded-but-authored/pinned session files
-   * are never orphaned.
-   */
-  currentExcludeSet: string[];
-  fileTombstones: ReadonlyMap<string, CompanyTombstone>;
-  /** Successful downloads since the last durable journal checkpoint. */
-  downloadsSinceJournalCheckpoint: number;
-}
-
-interface PullCounters {
-  filesDownloaded: number;
-  bytesDownloaded: number;
-  filesSkipped: number;
-  conflicts: number;
-  filesTombstoned: number;
-  filesOutOfScope: number;
-  conflictPaths: string[];
-  changedPaths: string[];
-}
-
-interface ScopeShrinkPlanState {
-  lastRecord: ReturnType<typeof lastPullRecord>;
-  shrinkPlan: ReturnType<typeof buildScopeShrinkPlan>;
-  autoRecover: boolean;
-  adviceContext: ScopeShrinkAdviceContext;
-  effectiveForce: boolean;
-}
-
-interface ScopeShrinkRun {
-  shrinkPlan: ReturnType<typeof buildScopeShrinkPlan>;
-  shrinkResult: ReturnType<typeof applyScopeShrink>;
-  scopeOrphansRemoved: number;
-  changedPaths: string[];
-}
-
-/**
- * Resolve the auto-prune safety cap (US-005 bulk-delete guard). An automatic
- * scope shrink that would delete more than this many CLEAN local files in one
- * pull is refused with `ScopeShrinkLargePruneError`. Default 100; `0` (or a
- * non-positive / unparseable value) disables the cap (unlimited). Override via
- * `HQ_SYNC_MAX_AUTO_PRUNE`.
- */
-export function resolveAutoPruneCap(): number {
-  const raw = process.env.HQ_SYNC_MAX_AUTO_PRUNE;
-  if (raw === undefined || raw === "") return 100;
-  const parsed = Number.parseInt(raw, 10);
-  // NaN or negative → treat as "unlimited" (0) rather than silently capping.
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
-}
-
-/** Max time to wait on the best-effort new-files notification POST. */
-const NOTIFY_FILE_ADDED_TIMEOUT_MS = 5000;
-/** Bound crash recovery to at most this many completed pull downloads. */
-const DOWNLOAD_JOURNAL_CHECKPOINT_BATCH_SIZE = 8;
-
-/**
- * Server cap on files per `/v1/notify/file-added` report. The endpoint rejects
- * an oversized batch wholesale, so the client MUST split a large report into
- * chunks at or under this size — otherwise a first sync with more than this many
- * new files reports none of them, and the same oversized batch re-triggers every
- * sync cycle (wasted work + dropped notifications). Keep in lockstep with the
- * server-side limit.
- */
-const NOTIFY_FILE_ADDED_MAX_BATCH = 1000;
-
-/**
- * Best-effort report of the files that were new to this drive during the sync,
- * so the HQ Sync app can show a persistent cross-session "new files" history.
- *
- * POSTs to `${apiUrl}/v1/notify/file-added`, which writes per-recipient
- * FILE_EVENT rows for the calling user (the one the files are new for). Fully
- * non-fatal: any error, non-2xx, or timeout is swallowed — the durable signal
- * is the synced file itself; this is only a notification mirror. Bounded by a
- * 5s timeout PER request so a hung endpoint can't stall sync completion. No-op
- * when there are no new files.
- *
- * Large reports are split into chunks of at most NOTIFY_FILE_ADDED_MAX_BATCH
- * files (the server's per-report cap). Each chunk is POSTed independently and
- * best-effort, so one failing/oversized batch can never block the others or the
- * sync. Exported only so the chunking can be unit-tested directly.
- */
-export async function reportNewFilesToNotify(
-  vaultConfig: VaultServiceConfig,
-  companyUid: string,
-  companySlug: string,
-  files: Array<{ path: string; bytes: number; addedBy: string | null }>,
-  telemetryClaims?: TelemetryClaims | null,
-): Promise<void> {
-  if (files.length === 0) return;
-
-  let token: string;
-  try {
-    token =
-      typeof vaultConfig.authToken === "function"
-        ? await vaultConfig.authToken()
-        : vaultConfig.authToken;
-  } catch (err) {
-    logNotifyFailure(err);
-    return;
-  }
-  const base = vaultConfig.apiUrl.replace(/\/+$/, "");
-  const telemetryClient = new VaultClient(vaultConfig);
-  const batchCount = Math.ceil(files.length / NOTIFY_FILE_ADDED_MAX_BATCH);
-
-  for (let i = 0; i < files.length; i += NOTIFY_FILE_ADDED_MAX_BATCH) {
-    const batch = files.slice(i, i + NOTIFY_FILE_ADDED_MAX_BATCH);
-    const batchIndex = Math.floor(i / NOTIFY_FILE_ADDED_MAX_BATCH) + 1;
-    const controller = new AbortController();
-    const timer = setTimeout(
-      () => controller.abort(),
-      NOTIFY_FILE_ADDED_TIMEOUT_MS,
-    );
-    try {
-      const response = await fetch(`${base}/v1/notify/file-added`, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${token}`,
-          "Content-Type": "application/json",
-        },
-        body: JSON.stringify({
-          companyUid,
-          companySlug,
-          files: batch.map((f) => ({
-            path: f.path,
-            bytes: f.bytes,
-            ...(f.addedBy ? { addedBy: f.addedBy } : {}),
-          })),
-        }),
-        signal: controller.signal,
-      });
-      if (!response.ok) {
-        void emitCloudTelemetry(telemetryClient, {
-          eventName: "new_files_notification_reported",
-          source: "hq-sync",
-          companyUid,
-          properties: {
-            status: "failure",
-            fileCount: batch.length,
-            batchIndex,
-            batchCount,
-            statusCode: response.status,
-          },
-        }, { claims: telemetryClaims });
-      }
-    } catch (err) {
-      // Best-effort per chunk: never let notification reporting affect the sync
-      // result, and a failed chunk must not abort the remaining chunks.
-      logNotifyFailure(err);
-      void emitCloudTelemetry(telemetryClient, {
-        eventName: "new_files_notification_reported",
-        source: "hq-sync",
-        companyUid,
-        properties: {
-          status: "failure",
-          fileCount: batch.length,
-          batchIndex,
-          batchCount,
-          errorClass: safeErrorName(err),
-        },
-      }, { claims: telemetryClaims });
-    } finally {
-      clearTimeout(timer);
-    }
-  }
-}
-
-function safeErrorName(err: unknown): string {
-  return err instanceof Error && err.name ? err.name : "error";
-}
-
-/** Log a non-fatal notify failure without ever throwing out of the logger. */
-function logNotifyFailure(err: unknown): void {
-  try {
-    console.error(
-      `[hq-sync] new-files notify report failed (non-fatal): ${
-        err instanceof Error ? err.message : String(err)
-      }`,
-    );
-  } catch {
-    // swallow — logging must never break sync
-  }
-}
-
-/** Log a non-fatal post-sync maintenance failure without changing sync state. */
-function logPostSyncMaintenanceFailure(
-  task: string,
-  hqRoot: string,
-  err: unknown,
-): void {
-  try {
-    console.error(
-      `[hq-sync] ${task} failed (non-fatal; hqRoot=${hqRoot}): ${
-        err instanceof Error ? err.message : String(err)
-      }`,
-    );
-  } catch {
-    // swallow — logging must never break sync
-  }
-}
-
-/**
- * Sync (pull) all allowed files from the entity vault.
- */
-export async function sync(options: SyncOptions): Promise<SyncResult> {
-  if (options.operationLockAlreadyHeld) {
-    return syncWithOperationLockHeld(options);
-  }
-  return withOperationLock(options.hqRoot, "sync", () =>
-    syncWithOperationLockHeld(options),
-  );
-}
-
-async function syncWithOperationLockHeld(
-  options: SyncOptions,
-): Promise<SyncResult> {
-  const run = await buildPullContext(options);
-  const plan = planPull(run);
-
-  emitPullPlan(run.emit, plan);
-  reportInvalidRemoteKeys(run, plan);
-
-  const scopePlan = planScopeShrink(run);
-  const scopeRun = executeScopeShrink(run, scopePlan);
-  const counters = createPullCounters();
-
-  const transferConcurrency = resolveTransferConcurrency();
-  const conflictRun = await executeConflictExecutor(
-    run,
-    plan,
-    scopeRun,
-    counters,
-  );
-  if (conflictRun.abortResult) {
-    return conflictRun.abortResult;
-  }
-
-  await executeDownloadExecutor(
-    run,
-    conflictRun.downloadItems,
-    transferConcurrency,
-    counters,
-  );
-
-  await emitAndReportNewFiles(run, plan);
-  await verifyPlannedJournalTombstones(run, plan);
-  executeJournalTombstoneDeletes(run, plan, counters);
-
-  emitScopeMaterializationGap(run, plan);
-
-  return finalizePullRun(run, plan, scopeRun, counters);
-}
-
-async function buildPullContext(options: SyncOptions): Promise<PullRunContext> {
-  const { company, vaultConfig, hqRoot } = options;
-  const baseEmit = options.onEvent ?? defaultConsoleLogger;
-
-  const companyRef = company ?? resolveActiveCompany(hqRoot);
-  if (!companyRef) {
-    throw new Error(
-      "No company specified and no active company found. " +
-      "Use --company <slug> or set up .hq/config.json.",
-    );
-  }
-
-  const ctx = await resolveEntityContext(companyRef, vaultConfig);
-  const companyRoot = options.personalMode === true
-    ? hqRoot
-    : path.join(hqRoot, "companies", ctx.slug);
-  const shouldSync = createIgnoreFilter(hqRoot);
-  const journalSlug = options.journalSlug ?? ctx.slug;
-  const startedAt = new Date().toISOString();
-
-  // Mirror every progress event into the shared cross-process snapshot so the
-  // menubar shows live progress for THIS sync regardless of who launched it
-  // (auto-sync / Sync Now / CLI). Record the friendly company slug (e.g.
-  // "indigo") — or null for the personal vault so the menubar shows "Personal"
-  // — never the raw prs_/cmp_ UID. Best-effort; never affects the sync.
-  const recordProgress = createSyncProgressRecorder({
-    company: options.personalMode === true ? null : ctx.slug,
-    phase: "pull",
-  });
-  const emit: SyncEventEmitter = (event) => {
-    baseEmit(event);
-    recordProgress(event);
-  };
-
-  if (journalSlug === PERSONAL_VAULT_JOURNAL_SLUG) migratePersonalVaultJournal();
-  const journal = migrateToV2(readJournal(journalSlug));
-  gcTombstones(journal, Date.now());
-
-  const syncMode: SyncMode = options.syncMode ?? "all";
-  const currentPrefixSet: string[] =
-    syncMode === "all" ? [""] : coalescePrefixes(options.prefixSet ?? []);
-  // Push-only exclusions (US-006). Coalesced independently of `currentPrefixSet`
-  // and applied to EVERY mode's download filter — including `all` — but kept out
-  // of the scope-shrink inputs (see `planScopeShrink`). Empty when the caller
-  // passes nothing (legacy behavior: no exclusions).
-  const currentExcludeSet: string[] = coalescePrefixes(
-    options.excludePrefixes ?? [],
-  );
-
-  const remoteFiles = await listRemoteFiles(ctx);
-  const fileTombstones =
-    options.personalMode === true
-      ? new Map<string, CompanyTombstone>()
-      : await fetchCompanyTombstones(vaultConfig, ctx.uid);
-
-  return {
-    options,
-    companyRef,
-    vaultConfig,
-    hqRoot,
-    emit,
-    ctx,
-    companyRoot,
-    shouldSync,
-    journalSlug,
-    startedAt,
-    journal,
-    remoteFiles,
-    syncMode,
-    currentPrefixSet,
-    currentExcludeSet,
-    fileTombstones,
-    downloadsSinceJournalCheckpoint: 0,
-  };
-}
-
-function planPull(run: PullRunContext): PullPlan {
-  return computePullPlan(
-    run.remoteFiles,
-    run.journal,
-    run.companyRoot,
-    run.shouldSync,
-    run.options.personalMode === true,
-    run.options.teamSyncedSlugs ?? null,
-    run.currentPrefixSet,
-    run.fileTombstones,
-    run.currentExcludeSet,
-  );
-}
-
-function emitPullPlan(emit: SyncEventEmitter, plan: PullPlan): void {
-  emit({
-    type: "plan",
-    filesToDownload: plan.filesToDownload,
-    bytesToDownload: plan.bytesToDownload,
-    filesToUpload: 0,
-    bytesToUpload: 0,
-    filesToSkip: plan.filesToSkip,
-    filesToConflict: plan.filesToConflict,
-    filesToDelete: plan.filesToTombstoneDelete,
-  });
-}
-
-/**
- * Surface permanently-unpresignable remote keys the planner skipped (see the
- * `invalidRemoteKeys` doc on PullPlan). One warning event per key on the
- * existing sync event channel (deliberately NOT `type: "error"` — see the
- * `skip-invalid-scoped-key` event doc), plus one best-effort cloud telemetry
- * event on the channel sync already uses (emitCloudTelemetry). Per policy
- * hq-alert-baseline-calibration the documented healthy baseline is ZERO
- * invalid-key occurrences fleet-wide, so consumers can alert on any non-zero
- * count with no threshold tuning.
- */
-function reportInvalidRemoteKeys(run: PullRunContext, plan: PullPlan): void {
-  if (plan.invalidRemoteKeys.length === 0) return;
-  const countsByErrorCode = new Map<string, number>();
-  for (const { path, errorCode } of plan.invalidRemoteKeys) {
-    run.emit({ type: "skip-invalid-scoped-key", path, errorCode });
-    countsByErrorCode.set(errorCode, (countsByErrorCode.get(errorCode) ?? 0) + 1);
-  }
-  for (const [errorCode, count] of countsByErrorCode) {
-    void emitCloudTelemetry(new VaultClient(run.vaultConfig), {
-      eventName: "sync_invalid_scoped_key_skipped",
-      source: "hq-sync",
-      companyUid: run.ctx.uid,
-      properties: { count, errorCode, leg: "pull" },
-    }, { claims: run.options.telemetryClaims });
-  }
-}
-
-/**
- * A legacy object without hq-mode can otherwise downgrade a hook to the
- * receiver umask with no durable signal. downloadFile already prints a local
- * warning for every caller; the sync path also records a path-free telemetry
- * event so operators can find vaults that still need the one-time backfill.
- */
-function reportModeWarnings(
-  run: PullRunContext,
-  warnings: DownloadModeWarning[] | undefined,
-): void {
-  for (const warning of warnings ?? []) {
-    void emitCloudTelemetry(new VaultClient(run.vaultConfig), {
-      eventName: "sync_mode_guardrail_warning",
-      source: "hq-sync",
-      companyUid: run.ctx.uid,
-      properties: {
-        leg: "pull",
-        reason: warning.reason,
-        fallback: warning.fallback ?? null,
-      },
-    }, { claims: run.options.telemetryClaims });
-  }
-}
-
-function createPullCounters(): PullCounters {
-  return {
-    filesDownloaded: 0,
-    bytesDownloaded: 0,
-    filesSkipped: 0,
-    conflicts: 0,
-    filesTombstoned: 0,
-    filesOutOfScope: 0,
-    conflictPaths: [],
-    changedPaths: [],
-  };
-}
-
-function planScopeShrink(run: PullRunContext): ScopeShrinkPlanState {
-  const lastRecord = lastPullRecord(run.journal, run.ctx.uid);
-  const lastPrefixSet =
-    lastRecord && lastRecord.prefixSet.length > 0
-      ? lastRecord.prefixSet
-      : [""];
-  const shrinkPlan = buildScopeShrinkPlan({
-    journal: run.journal,
-    hqRoot: run.companyRoot,
-    lastPrefixSet,
-    // INCLUSION scope only (+ pins, already folded into currentPrefixSet by the
-    // resolver). The push-only exclude set (US-006: `sessions/`) is DELIBERATELY
-    // NOT subtracted here: a session file that was authored locally
-    // (`direction:"up"`) or pinned + materialized on demand must never be
-    // orphaned just because sessions are excluded from the download filter.
-    // Feeding `currentExcludeSet` in here would prune exactly those files.
-    currentPrefixSet: run.currentPrefixSet,
-    callerSub: run.options.callerSub,
-    protectUnknownAuthors: true,
-  });
-  const scopeShrinkPolicy = run.options.scopeShrinkPolicy ?? "block";
-  const autoRecover = scopeShrinkPolicy === "auto-recover";
-  const adviceContext: ScopeShrinkAdviceContext = autoRecover ? "runner" : "cli";
-  const effectiveForce = run.options.forceScopeShrink === true || autoRecover;
-
-  return {
-    lastRecord,
-    shrinkPlan,
-    autoRecover,
-    adviceContext,
-    effectiveForce,
-  };
-}
-
-function executeScopeShrink(
-  run: PullRunContext,
-  scopePlan: ScopeShrinkPlanState,
-): ScopeShrinkRun {
-  const { lastRecord, shrinkPlan, adviceContext, effectiveForce } = scopePlan;
-
-  if (shrinkPlan.dirty.length > 0 && !effectiveForce) {
-    throw new ScopeShrinkBlockedError(
-      run.ctx.uid,
-      lastRecord?.syncMode ?? "unknown",
-      run.syncMode,
-      shrinkPlan.dirty,
-      shrinkPlan.clean,
-      adviceContext,
-    );
-  }
-
-  const autoPruneCap = resolveAutoPruneCap();
-  if (
-    !effectiveForce &&
-    autoPruneCap > 0 &&
-    shrinkPlan.clean.length > autoPruneCap
-  ) {
-    throw new ScopeShrinkLargePruneError(
-      run.ctx.uid,
-      run.syncMode,
-      shrinkPlan.clean.length,
-      autoPruneCap,
-      adviceContext,
-    );
-  }
-
-  const scopeQuarantineRoot = path.join(
-    run.hqRoot,
-    ".hq",
-    "scope-quarantine",
-    run.journalSlug,
-  );
-  const shrinkResult = applyScopeShrink({
-    journal: run.journal,
-    plan: shrinkPlan,
-    hqRoot: run.companyRoot,
-    forceScopeShrink: effectiveForce,
-    reason: "scope_shrink",
-    cleanDisposition: "quarantine",
-    quarantineRoot: scopeQuarantineRoot,
-  });
-
-  for (const relPath of shrinkResult.quarantinedPaths) {
-    run.emit({
-      type: "progress",
-      path: relPath,
-      bytes: 0,
-      deleted: true,
-      message: `scope-narrowed: moved out-of-scope copy to ${scopeQuarantineRoot}`,
-    });
-  }
-  for (const relPath of shrinkResult.removedPaths) {
-    run.emit({
-      type: "progress",
-      path: relPath,
-      bytes: 0,
-      deleted: true,
-      message: "scope-narrowed (removed local copy outside sync scope)",
-    });
-  }
-  for (const relPath of shrinkResult.dirtyKeptPaths) {
-    run.emit({
-      type: "progress",
-      path: relPath,
-      bytes: 0,
-      message:
-        "scope-narrowed: locally-modified file KEPT on disk, un-tracked from sync (outside scope)",
-    });
-  }
-
-  return {
-    shrinkPlan,
-    shrinkResult,
-    scopeOrphansRemoved:
-      shrinkResult.cleanRemoved + shrinkResult.cleanQuarantined,
-    changedPaths: [
-      ...shrinkResult.quarantinedPaths,
-      ...shrinkResult.removedPaths,
-    ],
-  };
-}
-
-async function refreshRunContextIfExpiring(
-  run: PullRunContext,
-): Promise<void> {
-  if (isExpiringSoon(run.ctx.expiresAt)) {
-    run.ctx = await refreshEntityContext(run.companyRef, run.vaultConfig);
-  }
-}
-
-async function executeConflictExecutor(
-  run: PullRunContext,
-  plan: PullPlan,
-  scopeRun: ScopeShrinkRun,
-  counters: PullCounters,
-): Promise<{ downloadItems: PullDownloadItem[]; abortResult: SyncResult | null }> {
-  const downloadItems: PullDownloadItem[] = [];
-
-  for (const item of plan.items) {
-    if (
-      item.action === "skip-ignored" ||
-      item.action === "skip-personal-mode" ||
-      item.action === "skip-unchanged" ||
-      item.action === "skip-local-only" ||
-      item.action === "skip-stale-overlay-marker" ||
-      item.action === "skip-overlay-marker-with-children"
-    ) {
-      counters.filesSkipped++;
-      continue;
-    }
-    if (item.action === "skip-unreadable-link") {
-      // An unreadable local link must stay non-fatal: the runner treats a
-      // generic error event as a failed company leg. Surface the exact remote
-      // key through the recoverable not-shipped channel instead.
-      counters.filesSkipped++;
-      run.emit({
-        type: "not-shipped",
-        reason: "unreadable-link",
-        count: 1,
-        samplePaths: [item.remoteFile.key],
-      });
-      continue;
-    }
-    if (item.action === "skip-excluded-policy") {
-      continue;
-    }
-    if (item.action === "skip-out-of-scope") {
-      counters.filesOutOfScope++;
-      continue;
-    }
-    if (item.action === "skip-junk-key-spelling") {
-      // Deliberate, recoverable skip — counted as skipped and surfaced via a
-      // dedicated warning event, never `type: "error"` (see the event doc /
-      // policy hq-sync-deliberate-skip-not-fatal-error-exit2).
-      counters.filesSkipped++;
-      run.emit({
-        type: "skip-junk-key-spelling",
-        path: item.remoteFile.key,
-        journaledKey: item.journaledKey,
-      });
-      continue;
-    }
-    if (item.action === "tombstone-delete") {
-      executeFileTombstoneDelete(run, item, counters);
-      continue;
-    }
-    if (item.action === "download") {
-      downloadItems.push(item);
-      continue;
-    }
-
-    const abortResult = await executeConflictItem(
-      run,
-      plan,
-      scopeRun,
-      counters,
-      downloadItems,
-      item,
-    );
-    if (abortResult) {
-      return { downloadItems, abortResult };
-    }
-  }
-
-  return { downloadItems, abortResult: null };
-}
-
-function executeFileTombstoneDelete(
-  run: PullRunContext,
-  item: Extract<PullPlanItem, { action: "tombstone-delete" }>,
-  counters: PullCounters,
-): void {
-  const tombstoneKey = item.remoteFile.key;
-  const tombstonePath = item.localPath;
-  if (!isDownloadWritePathStillContained(run.companyRoot, tombstoneKey, tombstonePath)) {
-    run.emit({
-      type: "error",
-      path: tombstoneKey,
-      message: "tombstone-suppress unlink skipped: local parent escaped the sync root",
-    });
-    return;
-  }
-  try {
-    const lstat = fs.lstatSync(tombstonePath);
-    if (!matchesLocalSnapshot(tombstonePath, item.localSnapshot)) {
-      reportLocalSnapshotConflict(run, counters, tombstoneKey);
-      return;
-    }
-    if (lstat.isSymbolicLink() || lstat.isFile()) {
-      fs.unlinkSync(tombstonePath);
-    }
-  } catch (err: unknown) {
-    const code =
-      err && typeof err === "object" && "code" in err
-        ? (err as { code?: string }).code
-        : undefined;
-    if (code !== "ENOENT") {
-      run.emit({
-        type: "error",
-        path: tombstoneKey,
-        message: `tombstone-suppress unlink failed: ${
-          err instanceof Error ? err.message : String(err)
-        }`,
-      });
-      return;
-    }
-  }
-  removeEntry(run.journal, tombstoneKey);
-  counters.filesTombstoned++;
-  counters.changedPaths.push(tombstoneKey);
-  run.emit({ type: "progress", path: tombstoneKey, bytes: 0 });
-}
-
-async function executeConflictItem(
-  run: PullRunContext,
-  plan: PullPlan,
-  scopeRun: ScopeShrinkRun,
-  counters: PullCounters,
-  downloadItems: PullDownloadItem[],
-  item: Extract<PullPlanItem, { action: "conflict" }>,
-): Promise<SyncResult | null> {
-  const { remoteFile, localPath } = item;
-
-  // Cloud-authoritative paths (server-regenerated: company-brief.md, board.json,
-  // ontology/ signals/ sources/) are PULL-WINS: the cloud copy is the source of
-  // truth, so a divergence here is not a real conflict. Resolve it as a normal
-  // overwrite-from-cloud — queue a plain download (which stamps the journal with
-  // the REMOTE hash/etag) and skip the conflict path entirely. This removes both
-  // the `.conflict-` mirror loop AND the journal false-stamp (remote etag over
-  // divergent local content) that the keep path produced for these files.
-  if (isCloudAuthoritative(vaultKeyForLocalPath(run.hqRoot, localPath))) {
-    downloadItems.push({
-      action: "download",
-      remoteFile,
-      localPath,
-      isNew: false,
-      localSnapshot: item.localSnapshot,
-    });
-    run.emit({ type: "reconciled", path: remoteFile.key, direction: "pull" });
-    return null;
-  }
-
-  await refreshRunContextIfExpiring(run);
-
-  const detectedAt = new Date().toISOString();
-  const machineId = readShortMachineId(run.hqRoot);
-  const originalRelative = vaultKeyForLocalPath(run.hqRoot, localPath);
-  const conflictRelative = buildConflictPath(
-    originalRelative,
-    detectedAt,
-    machineId,
-  );
-  const conflictAbs = localPathForVaultKey(run.hqRoot, conflictRelative);
-  const conflictKey = vaultKeyForLocalPath(run.companyRoot, conflictAbs);
-
-  if (!isDownloadWritePathStillContained(run.companyRoot, conflictKey, conflictAbs)) {
-    counters.filesSkipped++;
-    run.emit({
-      type: "error",
-      path: remoteFile.key,
-      message: "conflict mirror skipped: local parent escaped the sync root",
-    });
-    return null;
-  }
-
-  let remoteFetched = false;
-  let converged = false;
-  try {
-    const downloaded = await downloadFile(run.ctx, remoteFile.key, conflictAbs);
-    remoteFetched = true;
-    if (fs.lstatSync(conflictAbs).isSymbolicLink()) {
-      const target = readlinkOrNull(conflictAbs);
-      if (target === null) {
-        counters.filesSkipped++;
-        run.emit({
-          type: "not-shipped",
-          reason: "unreadable-link",
-          count: 1,
-          samplePaths: [remoteFile.key],
-        });
-        return null;
-      } else {
-        converged = hashSymlinkTarget(target) === item.localHash;
-      }
-    } else {
-      converged = (downloaded.contentHash ?? hashFile(conflictAbs)) === item.localHash;
-    }
-  } catch (probeErr) {
-    if (probeErr instanceof VaultAuthError) throw probeErr;
-    run.emit({
-      type: "error",
-      path: remoteFile.key,
-      message: `conflict convergence probe failed: ${
-        probeErr instanceof Error ? probeErr.message : String(probeErr)
-      }`,
-    });
-  }
-
-  if (converged) {
-    if (remoteFetched) {
-      try {
-        fs.rmSync(conflictAbs, { force: true });
-      } catch {
-        /* best-effort cleanup; a stray identical mirror is harmless */
-      }
-    }
-    updateEntry(
-      run.journal,
-      remoteFile.key,
-      item.localHash,
-      item.localSize,
-      "down",
-      localPath,
-      {
-        remoteEtag: remoteFile.etag,
-        mtimeMs: item.localMtime.getTime(),
-        kind: item.localSnapshot.kind === "symlink" ? "symlink" : "file",
-      },
-    );
-    run.emit({ type: "reconciled", path: remoteFile.key, direction: "pull" });
-    counters.filesSkipped++;
-    return null;
-  }
-
-  counters.conflicts++;
-  counters.conflictPaths.push(remoteFile.key);
-
-  const resolution = await resolveConflict(
-    {
-      path: remoteFile.key,
-      localHash: item.localHash,
-      remoteModified: remoteFile.lastModified,
-      localModified: item.localMtime,
-      direction: "pull",
-    },
-    run.options.onConflict,
-  );
-
-  run.emit({
-    type: "conflict",
-    path: remoteFile.key,
-    direction: "pull",
-    resolution,
-  });
-
-  if (resolution !== "abort" && resolution !== "overwrite") {
-    if (remoteFetched) {
-      try {
-        appendConflictEntry(run.hqRoot, {
-          id: buildConflictId(originalRelative, detectedAt),
-          originalPath: originalRelative,
-          conflictPath: conflictRelative,
-          detectedAt,
-          side: "pull",
-          machineId,
-          localHash: item.localHash,
-          remoteHash: remoteFile.etag ? normalizeEtag(remoteFile.etag) : "",
-        });
-      } catch (mirrorErr) {
-        run.emit({
-          type: "error",
-          path: remoteFile.key,
-          message: `conflict mirror index write failed: ${
-            mirrorErr instanceof Error ? mirrorErr.message : String(mirrorErr)
-          }`,
-        });
-      }
-    }
-  } else if (remoteFetched) {
-    try {
-      fs.rmSync(conflictAbs, { force: true });
-    } catch {
-      /* best-effort; a leftover mirror is cosmetic, not corrupting */
-    }
-  }
-
-  if (resolution === "abort") {
-    run.emit({ type: "new-files", files: [] });
-    writeJournal(run.journalSlug, run.journal);
-    return {
-      filesDownloaded: counters.filesDownloaded,
-      bytesDownloaded: counters.bytesDownloaded,
-      filesSkipped: counters.filesSkipped,
-      conflicts: counters.conflicts,
-      conflictPaths: counters.conflictPaths,
-      aborted: true,
-      newFiles: plan.newFiles,
-      newFilesCount: plan.newFilesCount,
-      filesExcludedByPolicy: plan.filesExcludedByPolicy,
-      filesTombstoned: 0,
-      filesOutOfScope: counters.filesOutOfScope,
-      scopeOrphansRemoved: scopeRun.scopeOrphansRemoved,
-      scopeOrphansBlocked: scopeRun.shrinkResult.dirtyTombstoned,
-      changedPaths: [...counters.changedPaths, ...scopeRun.changedPaths],
-    };
-  }
-
-  if (resolution === "keep" || resolution === "skip") {
-    counters.filesSkipped++;
-    updateEntry(
-      run.journal,
-      remoteFile.key,
-      item.localHash,
-      item.localSize,
-      "down",
-      localPath,
-      {
-        remoteEtag: remoteFile.etag,
-        mtimeMs: item.localMtime.getTime(),
-        kind: item.localSnapshot.kind === "symlink" ? "symlink" : "file",
-      },
-    );
-    // Journal-honesty: we recorded the remote etag so this conflict can't
-    // re-fire (#137), but the KEPT local copy diverges from that remote — it
-    // never matched it. Flag the entry so the currency-gated delete planner
-    // refuses to propagate a delete for it (its currency would falsely match on
-    // HEAD, and the delete would destroy the divergent remote version). Any
-    // genuine future download clears the flag by replacing the entry.
-    const keptEntry = getEntry(run.journal, remoteFile.key);
-    if (keptEntry) keptEntry.localDiverges = true;
-    return null;
-  }
-
-  downloadItems.push({
-    action: "download",
-    remoteFile,
-    localPath,
-    isNew: false,
-    localSnapshot: item.localSnapshot,
-  });
-  return null;
-}
-
-async function executeDownloadExecutor(
-  run: PullRunContext,
-  downloadItems: PullDownloadItem[],
-  transferConcurrency: number,
-  counters: PullCounters,
-): Promise<void> {
-  if (downloadItems.length === 0) return;
-
-  await primeObjectTransport(
-    run.ctx,
-    "get",
-    downloadItems.map((d) => d.remoteFile.key),
-  );
-
-  const queue = [...downloadItems];
-  const inFlight: Set<Promise<unknown>> = new Set();
-  const workerErrors: Error[] = [];
-
-  while (queue.length > 0 || inFlight.size > 0) {
-    while (inFlight.size < transferConcurrency && queue.length > 0) {
-      const downloadItem = queue.shift()!;
-      const p: Promise<void> = downloadOne(run, downloadItem, counters)
-        .catch((err: unknown) => {
-          workerErrors.push(err instanceof Error ? err : new Error(String(err)));
-        })
-        .finally(() => {
-          inFlight.delete(p);
-        });
-      inFlight.add(p);
-    }
-    if (inFlight.size > 0) {
-      await Promise.race(Array.from(inFlight));
-    }
-  }
-
-  if (workerErrors.length > 0) {
-    writeJournal(run.journalSlug, run.journal);
-    const first = workerErrors[0]!;
-    if (workerErrors.length > 1) {
-      first.message = `${first.message} (and ${workerErrors.length - 1} more download-worker errors)`;
-    }
-    throw first;
-  }
-}
-
-async function downloadOne(
-  run: PullRunContext,
-  downloadItem: PullDownloadItem,
-  counters: PullCounters,
-): Promise<void> {
-  const { remoteFile, localPath } = downloadItem;
-
-  await refreshRunContextIfExpiring(run);
-
-  if (!isDownloadWritePathStillContained(run.companyRoot, remoteFile.key, localPath)) {
-    counters.filesSkipped++;
-    run.emit({
-      type: "error",
-      path: remoteFile.key,
-      message: "download skipped: local parent escaped the sync root",
-    });
-    return;
-  }
-
-  try {
-    const { metadata, contentHash, contentSize, modeWarnings } = await downloadFile(
-      run.ctx,
-      remoteFile.key,
-      localPath,
-      {
-        beforeReplace: () => {
-          if (!matchesLocalSnapshot(localPath, downloadItem.localSnapshot)) {
-            throw new LocalSnapshotChangedError(remoteFile.key);
-          }
-        },
-      },
-    );
-    reportModeWarnings(run, modeWarnings);
-    const author = metadata?.["created-by"] ?? null;
-    const createdBySub = metadata?.["created-by-sub"];
-
-    const localLstat = fs.lstatSync(localPath);
-    const isLocalSymlink = localLstat.isSymbolicLink();
-    let hash: string;
-    if (isLocalSymlink) {
-      const target = readlinkOrNull(localPath);
-      if (target === null) {
-        counters.filesSkipped++;
-        run.emit({
-          type: "not-shipped",
-          reason: "unreadable-link",
-          count: 1,
-          samplePaths: [remoteFile.key],
-        });
-        return;
-      }
-      hash = hashSymlinkTarget(target);
-    } else {
-      hash = contentHash ?? hashFile(localPath);
-    }
-    const size = isLocalSymlink ? 0 : (contentSize ?? fs.statSync(localPath).size);
-
-    updateEntry(
-      run.journal,
-      remoteFile.key,
-      hash,
-      size,
-      "down",
-      localPath,
-      {
-        remoteEtag: remoteFile.etag,
-        mtimeMs: localLstat.mtimeMs,
-        ...(createdBySub !== undefined ? { createdBySub } : {}),
-        kind: isLocalSymlink ? "symlink" : "file",
-      },
-    );
-
-    const priorEntry = getEntry(run.journal, remoteFile.key);
-    const remoteJournalMessage = (priorEntry as { message?: string } | undefined)?.message;
-    run.emit({
-      type: "progress",
-      path: remoteFile.key,
-      bytes: size,
-      ...(remoteJournalMessage ? { message: remoteJournalMessage } : {}),
-      ...(author ? { author } : {}),
-    });
-
-    counters.filesDownloaded++;
-    counters.bytesDownloaded += size;
-    counters.changedPaths.push(remoteFile.key);
-  } catch (err) {
-    if (err instanceof VaultAuthError) throw err;
-    if (err instanceof LocalSnapshotChangedError) {
-      reportLocalSnapshotConflict(run, counters, remoteFile.key);
-    } else if (isAccessDenied(err)) {
-      counters.filesSkipped++;
-    } else if (err instanceof DanglingSymlinkParentError) {
-      // Per-object condition, not a company failure. The pre-flight
-      // containment check can miss this: it runs before the download, and a
-      // sibling worker in the SAME batch may materialize the parent symlink in
-      // between (the vault stores the link and the files beneath it as
-      // separate objects, ordered arbitrarily). Skip loudly — never silently —
-      // so the run stays `complete` instead of `errored` on every cycle.
-      counters.filesSkipped++;
-      run.emit({
-        type: "error",
-        path: remoteFile.key,
-        message: err.message,
-      });
-    } else {
-      run.emit({
-        type: "error",
-        path: remoteFile.key,
-        message: err instanceof Error ? err.message : String(err),
-      });
-    }
-    return;
-  }
-
-  run.downloadsSinceJournalCheckpoint++;
-  if (
-    run.downloadsSinceJournalCheckpoint >=
-    DOWNLOAD_JOURNAL_CHECKPOINT_BATCH_SIZE
-  ) {
-    // writeJournal is already fsync + rename atomic. Persist completed work
-    // before scheduling more objects so an abrupt process exit only replays a
-    // small tail, not an entire bulk download.
-    writeJournal(run.journalSlug, run.journal);
-    run.downloadsSinceJournalCheckpoint = 0;
-  }
-}
-
-async function emitAndReportNewFiles(
-  run: PullRunContext,
-  plan: PullPlan,
-): Promise<void> {
-  const enrichedNewFiles: Array<{ path: string; bytes: number; addedBy: string | null }> = [];
-  // Batch-mint the GET presigns once (chunked, breaker-aware) so the per-file
-  // created-by HEADs below reuse the cache instead of each minting its own
-  // presign. Without this, a big catch-up pull (hundreds of new files) bursts
-  // the presign endpoint, trips the circuit breaker, and every enrichment HEAD
-  // then fails. Mirrors the tombstone HEAD-verify pre-prime.
-  await primeObjectTransport(
-    run.ctx,
-    "get",
-    plan.newFiles.map((nf) => nf.path),
-  );
-  const HEAD_CONCURRENCY = 5;
-  for (let i = 0; i < plan.newFiles.length; i += HEAD_CONCURRENCY) {
-    const batch = plan.newFiles.slice(i, i + HEAD_CONCURRENCY);
-    const results = await Promise.all(
-      batch.map(async (nf) => {
-        let addedBy: string | null = null;
-        try {
-          const head = await headRemoteFile(run.ctx, nf.path);
-          if (head?.metadata?.["created-by"]) {
-            addedBy = head.metadata["created-by"];
-          }
-        } catch (headErr) {
-          if (headErr instanceof VaultAuthError) throw headErr;
-          try {
-            console.error(
-              `[hq-sync] HeadObject failed for ${nf.path}: ${
-                headErr instanceof Error ? headErr.message : String(headErr)
-              }`,
-            );
-          } catch {
-            // Swallow — logging must never break sync.
-          }
-        }
-        return { path: nf.path, bytes: nf.bytes, addedBy };
-      }),
-    );
-    enrichedNewFiles.push(...results);
-  }
-  run.emit({ type: "new-files", files: enrichedNewFiles });
-  await reportNewFilesToNotify(
-    run.vaultConfig,
-    run.ctx.uid,
-    run.ctx.slug,
-    enrichedNewFiles,
-    run.options.telemetryClaims,
-  );
-}
-
-async function verifyPlannedJournalTombstones(
-  run: PullRunContext,
-  plan: PullPlan,
-): Promise<void> {
-  if (plan.tombstones.length === 0) return;
-
-  // Scope-invalid journal keys (company mode, `companies/…` prefix) skip the
-  // HEAD verify: the presign transport's server validator rejects such keys
-  // outright (INVALID_KEY_COMPANIES_SCOPED), so a HEAD can never succeed and
-  // would defer the tombstone forever — leaving the poisoned journal entry
-  // (and its doubled-tree local file) re-firing on every sync. The key can
-  // never legitimately exist in a company vault, so treating it as verified
-  // is safe: the executor cleans the local copy + journal entry instead of
-  // the push leg ever re-uploading it (tombstone-not-reupload).
-  const autoVerified: PullPlan["tombstones"] = [];
-  const toHeadVerify: PullPlan["tombstones"] = [];
-  for (const tombstone of plan.tombstones) {
-    if (run.options.personalMode !== true && tombstone.key.startsWith("companies/")) {
-      autoVerified.push(tombstone);
-    } else {
-      toHeadVerify.push(tombstone);
-    }
-  }
-  plan.tombstones = toHeadVerify;
-  if (plan.tombstones.length === 0) {
-    plan.tombstones = autoVerified;
-    return;
-  }
-
-  await primeObjectTransport(run.ctx, "get", plan.tombstones.map((t) => t.key));
-
-  const HEAD_VERIFY_CONCURRENCY = 5;
-  const verified: PullPlan["tombstones"] = [];
-  for (let i = 0; i < plan.tombstones.length; i += HEAD_VERIFY_CONCURRENCY) {
-    const batch = plan.tombstones.slice(i, i + HEAD_VERIFY_CONCURRENCY);
-    const results = await Promise.all(
-      batch.map(async (tombstone) => {
-        try {
-          const head = await headRemoteFile(run.ctx, tombstone.key);
-          return head === null ? tombstone : null;
-        } catch (err) {
-          if (err instanceof VaultAuthError) throw err;
-          if (isAccessDenied(err)) return null;
-          run.emit({
-            type: "error",
-            path: tombstone.key,
-            message: `tombstone HEAD verify failed (deferring): ${
-              err instanceof Error ? err.message : String(err)
-            }`,
-          });
-          return null;
-        }
-      }),
-    );
-    for (const tombstone of results) {
-      if (tombstone !== null) verified.push(tombstone);
-    }
-  }
-  plan.tombstones = [...autoVerified, ...verified];
-}
-
-function executeJournalTombstoneDeletes(
-  run: PullRunContext,
-  plan: PullPlan,
-  counters: PullCounters,
-): void {
-  for (const tombstone of plan.tombstones) {
-    const { key, localPath, localSnapshot } = tombstone;
-    if (!isDownloadWritePathStillContained(run.companyRoot, key, localPath)) {
-      run.emit({
-        type: "error",
-        path: key,
-        message: "tombstone unlink skipped: local parent escaped the sync root",
-      });
-      continue;
-    }
-    let removedSomething = false;
-    try {
-      const lstat = fs.lstatSync(localPath);
-      if (!matchesLocalSnapshot(localPath, localSnapshot)) {
-        reportLocalSnapshotConflict(run, counters, key);
-        continue;
-      }
-      if (lstat.isSymbolicLink() || lstat.isFile()) {
-        fs.unlinkSync(localPath);
-        removedSomething = true;
-      } else if (lstat.isDirectory()) {
-        // A dir at a key is converged by dropping only the journal entry.
-      }
-    } catch (err: unknown) {
-      const code =
-        err && typeof err === "object" && "code" in err
-          ? (err as { code?: string }).code
-          : undefined;
-      if (code !== "ENOENT") {
-        run.emit({
-          type: "error",
-          path: key,
-          message: `tombstone unlink failed: ${
-            err instanceof Error ? err.message : String(err)
-          }`,
-        });
-        continue;
-      }
-    }
-    removeEntry(run.journal, key);
-    counters.filesTombstoned++;
-    counters.changedPaths.push(key);
-    run.emit({
-      type: "progress",
-      path: key,
-      bytes: 0,
-      deleted: true,
-      message: removedSomething ? "tombstone (cross-machine delete)" : "tombstone (already absent locally)",
-    });
-  }
-}
-
-function finalizePullRun(
-  run: PullRunContext,
-  plan: PullPlan,
-  scopeRun: ScopeShrinkRun,
-  counters: PullCounters,
-): SyncResult {
-  appendPullRecord(run.journal, {
-    pullId: generatePullId(),
-    companyUid: run.ctx.uid,
-    startedAt: run.startedAt,
-    completedAt: new Date().toISOString(),
-    syncMode: run.syncMode,
-    prefixSet: run.currentPrefixSet,
-    scopeChangeDetected: scopeRun.shrinkPlan.scopeChangeDetected,
-    orphansRemoved: scopeRun.scopeOrphansRemoved,
-    orphansBlocked: scopeRun.shrinkResult.dirtyTombstoned,
-  });
-
-  run.journal.lastSync = new Date().toISOString();
-  writeJournal(run.journalSlug, run.journal);
-
-  const changedOnDisk =
-    counters.filesDownloaded > 0 ||
-    counters.filesTombstoned > 0 ||
-    scopeRun.scopeOrphansRemoved > 0;
-  if (!run.options.skipReindex && changedOnDisk) {
-    try {
-      const result = reindex({ repoRoot: run.hqRoot, skipLock: true });
-      void emitCloudTelemetry(new VaultClient(run.vaultConfig), {
-        eventName: "reindex_run",
-        source: "hq-sync",
-        companyUid: run.ctx.uid,
-        properties: {
-          result: result.status === 0 ? "completed" : "failed",
-          statusCode: result.status,
-          lockResult: "skipped",
-          changedCount:
-            counters.changedPaths.length + scopeRun.changedPaths.length,
-        },
-      }, { claims: run.options.telemetryClaims });
-    } catch (err) {
-      logPostSyncMaintenanceFailure("post-sync reindex", run.hqRoot, err);
-      // best-effort: a post-sync refresh failure never fails the sync
-    }
-  }
-
-  return {
-    filesDownloaded: counters.filesDownloaded,
-    bytesDownloaded: counters.bytesDownloaded,
-    filesSkipped: counters.filesSkipped,
-    conflicts: counters.conflicts,
-    conflictPaths: counters.conflictPaths,
-    aborted: false,
-    newFiles: plan.newFiles,
-    newFilesCount: plan.newFilesCount,
-    filesExcludedByPolicy: plan.filesExcludedByPolicy,
-    filesTombstoned: counters.filesTombstoned,
-    filesOutOfScope: counters.filesOutOfScope,
-    scopeOrphansRemoved: scopeRun.scopeOrphansRemoved,
-    scopeOrphansBlocked: scopeRun.shrinkResult.dirtyTombstoned,
-    changedPaths: [...counters.changedPaths, ...scopeRun.changedPaths],
-  };
-}
-
-/**
- * Surface the shared-vs-all materialization gap (feedback_d2082110). When a
- * pull leg ran under a membership-scoped `syncMode` and skipped one or more
- * remote keys as out-of-scope, emit a single summary event so the operator
- * SEES that not all vault content materialized on this device and knows the
- * lever — raise the membership's access level to `all`. Silent in `all` mode
- * (nothing is scoped away) and when the membership scope withheld nothing: no
- * gap, no noise. Pure — count and samples are both read off the plan's
- * `skip-out-of-scope` items, no I/O.
- *
- * Counts ONLY `reason: "membership-scope"` items. `push-only` keys
- * (`sessions/`, US-006) are also classified `skip-out-of-scope` and also land
- * on the `filesOutOfScope` axis, but they are withheld in EVERY mode — `all`
- * included — so raising the access level does NOT materialize them. Counting
- * them here would inflate the gap, could fill `samplePaths` entirely with
- * session keys, and could fire the event (and its "set this membership to
- * `all`" advice) when the membership scope withheld nothing at all — sending
- * the operator back into exactly the flip-everything-to-`all`-and-still-miss
- * -files loop this event exists to end. `SyncResult.filesOutOfScope` keeps its
- * original both-causes meaning; only this advisory is narrowed.
- */
-function emitScopeMaterializationGap(run: PullRunContext, plan: PullPlan): void {
-  if (run.syncMode === "all") return;
-  const withheldByMembership = plan.items.filter(
-    (item) => item.action === "skip-out-of-scope" && item.reason === "membership-scope",
-  );
-  if (withheldByMembership.length === 0) return;
-  run.emit({
-    type: "scope-materialization-gap",
-    count: withheldByMembership.length,
-    samplePaths: withheldByMembership.slice(0, 10).map((item) => item.remoteFile.key),
-    syncMode: run.syncMode,
-  });
-}
-
-/**
- * Decide whether a remote object present in the LIST is a GENUINE RE-CREATE
- * written AFTER a FILE_TOMBSTONE — in which case the tombstone is stale and the
- * object must still sync (the tombstone is not permanent suppression). Returns
- * true to ALLOW the download (re-create), false to honor the tombstone.
- *
- * Decisive signal: the remote object's `lastModified` strictly newer than the
- * tombstone's `deletedAt`. A delete-marker + tombstone are written together at
- * delete time, so any object that post-dates the tombstone is a new write at
- * that key. An object at-or-before the tombstone is the deleted version (a
- * stale re-push or an un-propagated delete-marker) → honor the tombstone.
- *
- * Fail-OPEN (treat as re-create, allow download) when the comparison can't be
- * made — a malformed `deletedAt`, or no remote `lastModified`. Hiding a file the
- * user can see is worse than re-pulling one they deleted; the latter is
- * recoverable, the former looks like data loss.
- */
-function isRemoteRecreateAfterTombstone(
-  remote: { lastModified?: Date },
-  tombstone: CompanyTombstone,
-): boolean {
-  const deletedAtMs = Date.parse(tombstone.deletedAt);
-  if (Number.isNaN(deletedAtMs)) return true; // malformed tombstone → don't suppress
-  const remoteMs =
-    remote.lastModified instanceof Date
-      ? remote.lastModified.getTime()
-      : NaN;
-  if (Number.isNaN(remoteMs)) return true; // no remote timestamp → don't suppress
-  return remoteMs > deletedAtMs;
-}
-
-function hasTraversalSegment(key: string): boolean {
-  return key.split("/").some((segment) => segment === "..");
-}
-
-function isPathWithin(root: string, candidate: string): boolean {
-  const relative = path.relative(root, candidate);
-  return (
-    relative === "" ||
-    (!relative.startsWith("..") && !path.isAbsolute(relative))
-  );
-}
-
-function deepestExistingAncestor(start: string): string | null {
-  let current = start;
-  for (;;) {
-    try {
-      fs.lstatSync(current);
-      return current;
-    } catch (err: unknown) {
-      const code =
-        err && typeof err === "object" && "code" in err
-          ? (err as { code?: string }).code
-          : undefined;
-      if (code !== "ENOENT" && code !== "ENOTDIR") return null;
-    }
-
-    const parent = path.dirname(current);
-    if (parent === current) return null;
-    current = parent;
-  }
-}
-
-function resolveContainedVaultPath(root: string, key: string): string | null {
-  if (isMalformedVaultKey(key) || hasTraversalSegment(key)) return null;
-
-  const resolvedRoot = path.resolve(root);
-  const resolvedLocal = localPathForVaultKey(resolvedRoot, key);
-  if (!isPathWithin(resolvedRoot, resolvedLocal)) return null;
-
-  let realRoot: string;
-  try {
-    realRoot = fs.realpathSync.native(resolvedRoot);
-  } catch {
-    // If the vault root does not exist yet, no below-root symlink component can
-    // already exist to redirect this key. Preserve first-pull behavior.
-    return resolvedLocal;
-  }
-
-  const existingAncestor = deepestExistingAncestor(path.dirname(resolvedLocal));
-  if (existingAncestor === null) return null;
-  try {
-    const realAncestor = fs.realpathSync.native(existingAncestor);
-    if (!isPathWithin(realRoot, realAncestor)) return null;
-  } catch {
-    return null;
-  }
-  return resolvedLocal;
-}
-
-function isDownloadWritePathStillContained(
-  root: string,
-  key: string,
-  localPath: string,
-): boolean {
-  const resolved = resolveContainedVaultPath(root, key);
-  return resolved !== null && path.resolve(resolved) === path.resolve(localPath);
-}
-
-function snapshotLocalState(localPath: string): LocalSnapshot | null {
-  try {
-    const lstat = fs.lstatSync(localPath);
-    if (lstat.isSymbolicLink()) {
-      return { kind: "symlink", hash: hashSymlinkTarget(fs.readlinkSync(localPath)) };
-    }
-    if (lstat.isFile()) {
-      return { kind: "file", hash: hashFile(localPath) };
-    }
-    if (lstat.isDirectory()) return { kind: "directory" };
-    return { kind: "other" };
-  } catch (err: unknown) {
-    const code =
-      err && typeof err === "object" && "code" in err
-        ? (err as { code?: string }).code
-        : undefined;
-    return code === "ENOENT" ? { kind: "absent" } : null;
-  }
-}
-
-function matchesLocalSnapshot(localPath: string, expected: LocalSnapshot): boolean {
-  const actual = snapshotLocalState(localPath);
-  if (actual === null || actual.kind !== expected.kind) return false;
-  return (
-    (actual.kind !== "file" && actual.kind !== "symlink") ||
-    actual.hash === (expected as Extract<LocalSnapshot, { hash: string }>).hash
-  );
-}
-
-function hasCurrentLocalDeleteIntent(
-  entry: SyncJournal["files"][string] | undefined,
-): boolean {
-  const intent = entry?.localDeleteIntent;
-  return !!(
-    intent &&
-    intent.version === 1 &&
-    entry.remoteEtag &&
-    entry.kind &&
-    intent.remoteEtag === entry.remoteEtag &&
-    intent.localHash === entry.hash &&
-    intent.localKind === entry.kind
-  );
-}
-
-function reportLocalSnapshotConflict(
-  run: PullRunContext,
-  counters: PullCounters,
-  key: string,
-): void {
-  counters.conflicts++;
-  counters.conflictPaths.push(key);
-  run.emit({ type: "conflict", path: key, direction: "pull", resolution: "skip" });
-}
-
-class LocalSnapshotChangedError extends Error {
-  constructor(key: string) {
-    super(`local state changed while downloading ${key}; replanning required`);
-  }
-}
-
-/**
- * Stage-1 classification for a single remote object. Each remote file falls
- * into exactly one bucket; the executor in `sync()` switches on `action` to
- * decide what to do. `localHash` is carried on `conflict` items so the
- * executor can hand it to `resolveConflict` without re-hashing.
- */
-type LocalSnapshot =
-  | { kind: "absent" | "directory" | "other" }
-  | { kind: "file" | "symlink"; hash: string };
-
-/**
- * Why a remote key was classified `skip-out-of-scope`. The two causes look
- * identical in the count but have OPPOSITE remedies, so they must never be
- * reported as one: `membership-scope` is fixed by raising the membership's
- * access level to `all`; `push-only` is not fixed by that at all.
- */
-type OutOfScopeReason = "membership-scope" | "push-only";
-
-type PullPlanItem =
-  | {
-      action: "download";
-      remoteFile: RemoteFile;
-      localPath: string;
-      isNew: boolean;
-      localSnapshot: LocalSnapshot;
-    }
-  | { action: "skip-ignored"; remoteFile: RemoteFile; localPath: string }
-  | { action: "skip-personal-mode"; remoteFile: RemoteFile; localPath: string }
-  | { action: "skip-unchanged"; remoteFile: RemoteFile; localPath: string }
-  | { action: "skip-local-only"; remoteFile: RemoteFile; localPath: string }
-  // A local symlink was classified as a link but Windows (or a filesystem
-  // race) would not expose its target. This stays distinct from generic
-  // skip-local-only so the executor can report the exact path without making
-  // the whole company leg fail.
-  | { action: "skip-unreadable-link"; remoteFile: RemoteFile; localPath: string }
-  // A stale personal-overlay symlink marker in the vault sitting at a key that
-  // is ALSO a real, release-shipped core directory (e.g. an old
-  // `core/knowledge/public/agent-browser` overlay marker after a release
-  // shipped a real directory of the same name). The local release-shipped
-  // directory is authoritative; the marker is inert derived state that must
-  // NEVER overwrite core. Distinct from skip-local-only so the benign,
-  // no-action-needed case is never surfaced with the alarming "rm -rf the
-  // local directory" reconciliation advice.
-  | { action: "skip-stale-overlay-marker"; remoteFile: RemoteFile; localPath: string }
-  // A directory-overlay marker (a single vault object at a key that ALSO has
-  // child objects under it in the same LIST — a symlink record for a directory
-  // mirrored from another tree) colliding with a local REAL directory whose
-  // contents are already materialized. The marker can never be renamed over the
-  // directory; its children carry the real content and materialize via their own
-  // plan items. A benign, no-action skip — distinct from skip-local-only so the
-  // case is never surfaced with the alarming (and, for a materialized directory,
-  // data-destroying) "rm -rf the local directory to pull" advice. feedback_d2082110.
-  | { action: "skip-overlay-marker-with-children"; remoteFile: RemoteFile; localPath: string }
-  // Remote keys refused by ephemeral-mirror policy. The push walker has
-  // refused to upload these since 5.33.0; the pull walker now refuses to
-  // download them so legacy litter in cloud staging drains naturally.
-  | { action: "skip-excluded-policy"; remoteFile: RemoteFile; localPath: string }
-  // Remote keys present in the remote LIST (and accessible per STS) but
-  // deliberately not downloaded. Two DIFFERENT causes share this action and
-  // the `filesOutOfScope` count, so `reason` discriminates them:
-  //
-  //   `membership-scope` — outside the effective `syncMode` prefix set
-  //     (US-005). RAISING the membership's access level to `all` WOULD
-  //     materialize these keys.
-  //   `push-only`        — under a push-only exclude prefix (`sessions/`,
-  //     US-006). These are withheld in EVERY mode, `all` included; raising
-  //     the access level does NOT materialize them (`hq files get` does).
-  //
-  // Only `membership-scope` items may be attributed to the shared-vs-all gap
-  // — see `emitScopeMaterializationGap`. feedback_d2082110.
-  | {
-      action: "skip-out-of-scope";
-      remoteFile: RemoteFile;
-      localPath: string;
-      reason: OutOfScopeReason;
-    }
-  | {
-      // Mixed-version amplifier guard — see the `skip-junk-key-spelling`
-      // event doc. Carries the journaled spelling for the warning surface.
-      action: "skip-junk-key-spelling";
-      remoteFile: RemoteFile;
-      localPath: string;
-      journaledKey: string;
-    }
-  // Remote key present in the LIST but carrying a FILE_TOMBSTONE that marks it
-  // intentionally deleted (and the remote object is NOT a newer re-create). The
-  // executor deletes any local copy and drops the journal entry — the
-  // authoritative-delete arm of delete-resync. Unlike `PullPlan.tombstones`
-  // (keys ABSENT from the LIST, HEAD-verified before delete), these are
-  // suppressed purely on the FILE_TOMBSTONE authority and skip HEAD-verify (the
-  // remote object is present by definition).
-  | {
-      action: "tombstone-delete";
-      remoteFile: RemoteFile;
-      localPath: string;
-      localSnapshot: LocalSnapshot;
-    }
-  | {
-      action: "conflict";
-      remoteFile: RemoteFile;
-      localPath: string;
-      localHash: string;
-      // Captured from the planner's lstat (does NOT follow symlinks),
-      // so a dangling symlink doesn't make the conflict executor
-      // statSync-then-ENOENT and abort the whole pull. See the
-      // executor: prior to this field, the prompt builder called
-      // fs.statSync(localPath).mtime to populate the conflict UI's
-      // "local modified at X" line, which crashed for dangling links.
-      localMtime: Date;
-      // Symlink-aware size for the post-resolution journal stamp.
-      // For a symlink, journal convention is 0 (the wire body is
-      // empty + target metadata; matches what the push side stamps).
-      // For a regular file, mirrors the on-disk byte length. The
-      // executor's keep/skip branch reads this instead of calling
-      // fs.statSync(localPath), which would follow a dangling link
-      // and silently fail to stamp the journal — leaving the
-      // conflict to re-fire forever.
-      localSize: number;
-      localSnapshot: LocalSnapshot;
-    };
-
-interface PullPlan {
-  items: PullPlanItem[];
-  filesToDownload: number;
-  bytesToDownload: number;
-  filesToSkip: number;
-  filesToConflict: number;
-  /** Files classified as new (no local counterpart at classification time). */
-  newFiles: Array<{ path: string; bytes: number }>;
-  newFilesCount: number;
-  /** Count of remote keys refused by ephemeral-mirror policy. */
-  filesExcludedByPolicy: number;
-  /** Count of remote keys skipped because they fall outside the sync scope. */
-  filesOutOfScope: number;
-  /**
-   * Journal-known keys missing from the remote LIST. The executor will
-   * apply each as a local delete (file or symlink) + journal removal,
-   * propagating the peer's push-side delete cross-machine (Bug #9).
-   * Carried on the plan so the executor can iterate without re-walking.
-   */
-  tombstones: Array<{
-    key: string;
-    localPath: string;
-    localSnapshot: LocalSnapshot;
-  }>;
-  /**
-   * Count of `tombstone-delete` items — remote keys present in the LIST but
-   * suppressed by a FILE_TOMBSTONE (delete-resync). Surfaced on the plan event's
-   * `filesToDelete` axis; the per-item executor applies the local delete.
-   */
-  filesToTombstoneDelete: number;
-  /**
-   * Remote keys skipped because the server will never presign them. Counted in
-   * `filesExcludedByPolicy`; carried with the server-compatible error code so
-   * the caller can log one warning per key and emit telemetry. Healthy
-   * baseline is an empty array (policy
-   * hq-alert-baseline-calibration: zero expected, any occurrence is signal).
-   */
-  invalidRemoteKeys: Array<{ path: string; errorCode: string }>;
-}
-
-/**
- * Stage-1 planning pass: classify every remote file into download / skip /
- * conflict buckets without performing any S3 transfers. Local hashes are
- * computed here (not in the transfer loop) so the totals returned reflect
- * the real outcome of the upcoming Stage-2 execution rather than an
- * upper-bound guess.
- *
- * Pure function: no S3 calls, no journal writes, no event emission. The
- * caller (`sync()`) is responsible for emitting the resulting plan event
- * before iterating `items`.
- */
-// Pull-leg intentional-delete bulk-asymmetry breaker. Mirrors the push leg's
-// BULK_ASYMMETRY_* (share.ts): an abnormally large fraction of clean files
-// vanishing at once is a corrupt mirror / bulk op / unmount (the ridge-incident
-// class), not intent — so at/above the threshold the pull leg drift-restores
-// every candidate instead of tombstoning it. Below it, a missing clean file is
-// an intentional delete.
-const PULL_INTENTIONAL_DELETE_MIN_ABS = 10;
-const PULL_INTENTIONAL_DELETE_RATIO = 0.1;
-
-/**
- * win32 only: true when an existing local symlink's TARGET exists but the
- * link cannot be traversed as that target's type — the file-flavor-link-at-
- * a-directory shape minted while the target was absent (or by an older
- * client). A dangling link is NOT broken-flavored (there is nothing to
- * repair until the target appears). POSIX links are flavorless: always
- * false off win32.
- */
-export function win32SymlinkFlavorBroken(
-  localPath: string,
-  win32: boolean = process.platform === "win32",
-): boolean {
-  if (!win32) return false;
-  let target: string;
-  try {
-    target = fs.readlinkSync(localPath);
-  } catch {
-    return false;
-  }
-  const resolved = path.resolve(path.dirname(localPath), target);
-  let targetIsDir: boolean;
-  try {
-    targetIsDir = fs.statSync(resolved).isDirectory();
-  } catch {
-    return false; // dangling target — nothing to repair yet
-  }
-  try {
-    return fs.statSync(localPath).isDirectory() !== targetIsDir;
-  } catch {
-    return true; // target exists but the link cannot traverse: wrong flavor
-  }
-}
-
-function computePullPlan(
-  remoteFiles: RemoteFile[],
-  journal: SyncJournal,
-  companyRoot: string,
-  shouldSync: (filePath: string, isDir?: boolean) => boolean,
-  personalMode: boolean,
-  teamSyncedSlugs: ReadonlySet<string> | null,
-  // Coalesced, company-relative prefixes the pull is scoped to (US-005).
-  // `[""]` (the `all`-mode value) covers everything via `isCoveredByAny`, so
-  // the scope filter below becomes a no-op and legacy behavior is preserved.
-  prefixSet: readonly ScopePrefixInput[],
-  // FILE_TOMBSTONE records (POSIX-keyed) for the company — the durable
-  // "this key was intentionally deleted" signal the planner consults before
-  // re-downloading a key, so a deleted folder does not resync back in
-  // (delete-resync). An empty map (the default / degraded-fetch case)
-  // preserves the legacy behavior bit-for-bit. (Named `fileTombstones` to avoid
-  // shadowing the local `tombstones` string[] — the journal-vs-LIST delete set.)
-  fileTombstones: ReadonlyMap<string, CompanyTombstone> = new Map(),
-  // Push-only exclusion prefixes (US-006: `sessions/`). Keys covered by any of
-  // these are classified `skip-out-of-scope` in EVERY mode — including `all` —
-  // AFTER passing the inclusion check. Empty (the default) preserves legacy
-  // behavior bit-for-bit. Applied ONLY here (the download filter), never to
-  // scope-shrink, so an authored/pinned excluded key is not re-pulled yet also
-  // never orphaned.
-  excludePrefixes: readonly ScopePrefixInput[] = [],
-): PullPlan {
-  const items: PullPlanItem[] = [];
-  // Remote keys the server will never presign — collected so the caller can
-  // warn + emit telemetry without allowing one poison object to fail a pull.
-  const invalidRemoteKeys: Array<{ path: string; errorCode: string }> = [];
-  // Clean/current/non-divergent files missing locally — collected here, then
-  // resolved post-loop by the bulk-asymmetry decision (tombstone vs. restore).
-  const intentionalDeleteCandidates: Array<{
-    remoteFile: RemoteFile;
-    localPath: string;
-  }> = [];
-
-  // Junk-spelling guard (mixed-version amplifier): index every journaled key
-  // by its canonical (percent-decode fixpoint) form so a remote twin minted
-  // under a different spelling is recognized before it materializes. When
-  // several journaled spellings already share one canonical form (a
-  // pre-guard fork), the exactly-canonical spelling is preferred as the
-  // representative; entries journaled under their own exact spelling are
-  // never gated by this map (see the guard below), so pre-existing families
-  // keep syncing untouched until the vault doctor (US-003) collapses them.
-  const journaledKeyByCanonical = new Map<string, string>();
-  for (const journaledKey of Object.keys(journal.files)) {
-    if (!journaledKey.startsWith(SKILLS_KEY_PREFIX)) continue;
-    const canonical = canonicalVaultKeySpelling(journaledKey);
-    const existing = journaledKeyByCanonical.get(canonical);
-    if (existing === undefined || journaledKey === canonical) {
-      journaledKeyByCanonical.set(canonical, journaledKey);
-    }
-  }
-
-  // Remote keys that ALSO appear as an ancestor of another remote key — i.e.
-  // keys that carry child objects under `${key}/…` in this same LIST. The
-  // vault stores a directory OVERLAY (a symlink into another tree, e.g. a
-  // company skill mirrored from a shared repo) as a symlink RECORD at the
-  // directory's own key AND stores the directory's contents as separate child
-  // objects beneath it. A REAL directory, by contrast, only ever syncs as
-  // those child objects — never as a single object AT its own key. So a single
-  // remote object sitting at a key that also has children is unambiguously a
-  // directory-overlay marker, not a regular file. Precomputed once (pure path
-  // derivation, no I/O — the planner is synchronous) so the dir-vs-object
-  // collision branch can tell an inert overlay marker apart from a genuine
-  // file-vs-directory structural collision. feedback_d2082110.
-  const remoteKeysWithChildren = new Set<string>();
-  for (const rf of remoteFiles) {
-    const key = toPosixKey(rf.key);
-    let slash = key.indexOf("/");
-    while (slash !== -1) {
-      remoteKeysWithChildren.add(key.slice(0, slash));
-      slash = key.indexOf("/", slash + 1);
-    }
-  }
-
-  for (const remoteFile of remoteFiles) {
-    const invalidKey = classifyVaultKey(
-      remoteFile.key,
-      personalMode ? "personal" : "company",
-    );
-    if (invalidKey !== null) {
-      invalidRemoteKeys.push({
-        path: remoteFile.key,
-        errorCode: invalidKey.code,
-      });
-      items.push({
-        action: "skip-excluded-policy",
-        remoteFile,
-        localPath: companyRoot,
-      });
-      continue;
-    }
-
-    const localPath = resolveContainedVaultPath(companyRoot, remoteFile.key);
-    if (localPath === null) {
-      items.push({ action: "skip-excluded-policy", remoteFile, localPath: companyRoot });
-      continue;
-    }
-
-    // Ephemeral-mirror filter — symmetric with the push-side walker. Bug #2
-    // in the 5.33.0 deep-test: the push side has refused to upload conflict
-    // mirrors since 5.33.0, but the pull side downloaded them freely from
-    // staging, so legacy `.conflict-*` litter rode every sync into clean
-    // trees. Refuse them here; the V2 verification test (direct S3 inject
-    // bypassing the push filter entirely) is the regression contract.
-    if (isEphemeralPath(remoteFile.key)) {
-      items.push({ action: "skip-excluded-policy", remoteFile, localPath });
-      continue;
-    }
-
-    // Company-vault double-scoped-key filter. A company vault is already
-    // anchored at its company root, so a remote key under `companies/...` is a
-    // corrupt doubly-scoped object the vault-service refuses to presign
-    // (INVALID_KEY_COMPANIES_SCOPED). Without this, the puller enqueues it, the
-    // per-file GET fails, and the whole company wedges at "errored" (runner
-    // exit 2) on every run (frogbear, 2026-06-16). Refuse at plan time,
-    // symmetric with the malformed/ephemeral filters above. Personal vaults
-    // handle `companies/...` keys in the dedicated branch below.
-    if (isForbiddenCompanyVaultKey(remoteFile.key, personalMode)) {
-      items.push({ action: "skip-excluded-policy", remoteFile, localPath });
-      continue;
-    }
-
-    // Personal-vault policy must be symmetric across both transfer legs.
-    // The push walker refuses derived/machine-local/sensitive paths, but old
-    // objects can remain in the bucket from clients that predate an exclusion.
-    // Refuse those objects here too so a pull cannot rematerialize them (or,
-    // for generated skill wrappers, fight reindex over a directory link).
-    if (personalMode && isPersonalVaultExcluded(remoteFile.key)) {
-      items.push({ action: "skip-excluded-policy", remoteFile, localPath });
-      continue;
-    }
-
-    if (
-      personalMode &&
-      remoteFile.key.startsWith("companies/") &&
-      // EXEMPTION: companies/manifest.yaml is the routing source-of-truth
-      // carved INTO the personal vault on the push side
-      // (computePersonalVaultPaths). It must round-trip on the pull leg too —
-      // skipping it here leaves it forever unjournaled, which re-fires a
-      // transient push-side conflict every sync (no journal baseline). Let it
-      // fall through to download + journal like any personal file.
-      remoteFile.key !== PERSONAL_VAULT_MANIFEST_KEY
-    ) {
-      // Local (non-cloud) companies sync to the personal vault: keys under
-      // `companies/{slug}/...` are legitimate content a peer machine pushed
-      // for a company that is not cloud-backed. Allow them through EXCEPT
-      // for slugs the operator has an active team-bucket Membership for:
-      // those are orphan remnants from before the company became cloud-true,
-      // and downloading them would clash with the team-bucket pull at the
-      // same disk path.
-      //
-      // Symmetric to the push-side `decommissionPrefixes` logic in
-      // share.ts — both target the same orphan class, both honor the
-      // same `teamSyncedSlugs` set derived from the operator's live
-      // membership at runtime.
-      const slug = remoteFile.key.split("/")[1] ?? "";
-      const isTeamSyncedOrphan =
-        teamSyncedSlugs !== null && slug !== "" && teamSyncedSlugs.has(slug);
-      if (isTeamSyncedOrphan) {
-        items.push({ action: "skip-personal-mode", remoteFile, localPath });
-        continue;
-      }
-    }
-
-    // Scope filter (US-005). Keys outside the effective `syncMode` prefix set
-    // are not downloaded. `prefixSet` is `[""]` in `all` mode, which
-    // `isCoveredByAny` treats as covering everything — so this is a no-op for
-    // `all` and preserves the legacy full-bucket pull bit-for-bit. The
-    // previously-downloaded counterparts of these keys (if scope just shrank)
-    // are pruned separately by the scope-shrink pass in `sync()`.
-    // A key can fail the inclusion check AND sit under a push-only exclude
-    // prefix. Attribute it to `push-only` in that case: widening the
-    // membership to `all` would move it into `prefixSet` but the exclusion
-    // below would still withhold it, so it is NOT part of the shared-vs-all
-    // gap and must not be advertised as fixable by raising the access level.
-    if (!isCoveredByAny(remoteFile.key, prefixSet)) {
-      items.push({
-        action: "skip-out-of-scope",
-        remoteFile,
-        localPath,
-        reason: isCoveredByAny(remoteFile.key, excludePrefixes)
-          ? "push-only"
-          : "membership-scope",
-      });
-      continue;
-    }
-
-    // Push-only exclusion filter (US-006). A key that PASSED the inclusion check
-    // above is STILL not downloaded if it falls under a push-only exclude prefix
-    // (`sessions/`). This is what makes sessions push-only in EVERY mode — it
-    // subtracts from `all` (whose `prefixSet` is `[""]`, covering everything)
-    // and from an owner's role-wide scope alike. Empty `excludePrefixes` (the
-    // default) makes this a no-op. Deliberately AFTER inclusion and reported on
-    // the same `filesOutOfScope` axis. The matching local file (if a session was
-    // previously pulled, authored locally, or pinned+materialized) is NOT pruned
-    // here or by scope-shrink — see `planScopeShrink`, which never sees this set.
-    if (isCoveredByAny(remoteFile.key, excludePrefixes)) {
-      items.push({
-        action: "skip-out-of-scope",
-        remoteFile,
-        localPath,
-        reason: "push-only",
-      });
-      continue;
-    }
-
-    // LIST gives us no kind signal for the remote object — we don't
-    // know whether this key is a regular file or a symlink record
-    // until we either HEAD it (expensive — N extra calls per pull) or
-    // download it. So probe the ignore filter with BOTH isDir hints
-    // and include the entry if either probe passes. Without this,
-    // a symlink record at a dir-only-allowlisted path (e.g. an
-    // .hqinclude of `companies/*/knowledge/`) would be classified
-    // skip-ignored and the symlinks freshly uploaded by the
-    // push-side fix would never propagate. Mirrors the dual-hint
-    // probe in walkDir/collectFiles. Pure path lookup, no I/O.
-    if (!shouldSync(localPath, false) && !shouldSync(localPath, true)) {
-      items.push({ action: "skip-ignored", remoteFile, localPath });
-      continue;
-    }
-
-    const journalEntry = getEntry(journal, remoteFile.key);
-
-    // Reindex and package wiring own symlinks under these `core/<type>`
-    // surfaces; their canonical sources are elsewhere. A prior pull records
-    // the remote object as a symlink, then reindex removes the generated link.
-    // Without this classification the next pull sees only an absent local path
-    // and downloads the same marker forever. Retain regular core files: the
-    // journal kind is the discriminator, because LIST exposes no object type.
-    // An unchanged ETag is also required: a remote writer can replace a legacy
-    // symlink with canonical file content at the same key, and that replacement
-    // must still be pulled.
-    if (
-      personalMode &&
-      journalEntry?.kind === "symlink" &&
-      isGeneratedCoreMirrorKey(remoteFile.key) &&
-      journalEntry.remoteEtag !== undefined &&
-      !hasRemoteChanged(remoteFile, journalEntry)
-    ) {
-      items.push({ action: "skip-excluded-policy", remoteFile, localPath });
-      continue;
-    }
-
-    // Junk-spelling guard — SKILL-FARM KEYS ONLY. The amplifier is specific
-    // to `.claude/skills/<ns>:<skill>` wrapper spellings; outside that prefix,
-    // keys whose percent-decode fixpoints collide (`notes/a b.md` vs a genuine
-    // `notes/a%20b.md`) are DISTINCT files that must both pull.
-    // Within the farm: a remote key that is NOT journaled under its own
-    // spelling but whose percent-decode fixpoint matches an already-journaled
-    // key with a different spelling is a mixed-version twin (`%3A`/`%253A`
-    // generations of a canonical `:` key). Materializing it would mint junk
-    // local dirs and fork the journal into a second key family for the same
-    // logical path — skip it (loudly, never fatally; see the
-    // `skip-junk-key-spelling` event doc) and leave the journaled spelling
-    // authoritative for this machine.
-    if (
-      journalEntry === undefined &&
-      remoteFile.key.startsWith(SKILLS_KEY_PREFIX) &&
-      // Gate NON-canonical remote spellings only. A remote key that already
-      // IS the canonical spelling must always be downloadable — after the
-      // doctor collapses the vault, a machine whose journal still holds only
-      // the junk spelling would otherwise skip the canonical object forever
-      // (and the delete-resync twin protection keeps that stale junk entry),
-      // deadlocking it out of every future update.
-      canonicalVaultKeySpelling(remoteFile.key) !== remoteFile.key
-    ) {
-      const journaledTwin = journaledKeyByCanonical.get(
-        canonicalVaultKeySpelling(remoteFile.key),
-      );
-      if (journaledTwin !== undefined && journaledTwin !== remoteFile.key) {
-        items.push({
-          action: "skip-junk-key-spelling",
-          remoteFile,
-          localPath,
-          journaledKey: journaledTwin,
-        });
-        continue;
-      }
-    }
-
-    // ── FILE_TOMBSTONE consult (delete-resync) ───────────────────────────────
-    // A remote object present in the LIST may be an intentionally-deleted key
-    // (a peer re-pushed it, or its delete-marker hasn't propagated to this
-    // caller's view). `tombstoneSuppresses` is true when a FILE_TOMBSTONE marks
-    // this key deleted AND the remote object is NOT a newer re-create — i.e. the
-    // object is the stale/deleted version and must NOT be downloaded. A genuine
-    // re-create (object newer than the tombstone) leaves this false so the
-    // normal download/merge path runs (the tombstone is not permanent
-    // suppression). An empty tombstone map (the default / degraded-fetch case)
-    // makes this always false — legacy behavior preserved bit-for-bit.
-    const tombstone = fileTombstones.get(toPosixKey(remoteFile.key));
-    const tombstoneSuppresses =
-      tombstone !== undefined &&
-      !isRemoteRecreateAfterTombstone(remoteFile, tombstone);
-    // LOCAL journal tombstone — this machine's own intentional-delete record,
-    // independent of the (best-effort, intermittently-degraded) server
-    // FILE_TOMBSTONE fetch above. When a clean local delete is classified, the
-    // push leg stamps `removedAt` on the journal entry; honoring it here makes
-    // the delete-vs-drift-restore outcome DETERMINISTIC, closing the
-    // intermittent respawn where a degraded tombstone fetch let the pull leg
-    // re-materialize an intentionally-deleted file. Reuses the same re-create
-    // guard (a remote object newer than the local delete is a genuine re-create
-    // and still downloads). Consulted ONLY on the `!localExists` re-download
-    // path below — never to delete a file that is present locally.
-    const localTombstoneSuppresses =
-      journalEntry !== undefined &&
-      isTombstone(journalEntry) &&
-      hasCurrentLocalDeleteIntent(journalEntry) &&
-      journalEntry.removedAt !== undefined &&
-      !isRemoteRecreateAfterTombstone(remoteFile, {
-        deletedAt: journalEntry.removedAt,
-      });
-
-    // lstat (not existsSync/statSync) handles three cases the legacy
-    // checks got wrong for symlinks:
-    //   1. A valid symlink at localPath: existsSync returns true and the
-    //      planner falls through to hashFile, which follows the link and
-    //      hashes the target file's bytes — never matching the journal's
-    //      sha256(target string), so every pull would mis-classify a
-    //      pristine symlink as locally changed.
-    //   2. A dangling symlink: existsSync returns false (existsSync
-    //      follows links) so the planner treats the entry as missing and
-    //      re-downloads, silently clobbering the user's intentional
-    //      dangling link on every run.
-    //   3. A regular file: indistinguishable from current behaviour.
-    let localLstat: fs.Stats | null = null;
-    let plannedLocalSnapshot: LocalSnapshot = { kind: "absent" };
-    let localPathBlockedByFileAncestor = false;
-    try {
-      localLstat = fs.lstatSync(localPath);
-    } catch (err: unknown) {
-      const code =
-        err && typeof err === "object" && "code" in err
-          ? (err as { code?: string }).code
-          : undefined;
-      // ENOENT  → truly absent → treated as "new file from cloud".
-      // ENOTDIR → an ancestor of localPath is a regular file (cloud has a
-      //           dir at that key, local has a file). Pre-fix this threw
-      //           and aborted the whole company sync (Bug #10 in the
-      //           5.33.0 deep-test verification — \`v4-dir-vs-file\` repro
-      //           wedged the personal company at \"errored\" status,
-      //           skipping every later file). Recover by classifying as
-      //           a structural collision the operator must resolve
-      //           manually, and let the rest of the company process.
-      if (code !== "ENOENT" && code !== "ENOTDIR") {
-        throw err;
-      }
-      if (code === "ENOTDIR") {
-        localPathBlockedByFileAncestor = true;
-      }
-    }
-    const localExists = localLstat !== null;
-
-    if (localPathBlockedByFileAncestor) {
-      // Symmetric counterpart to the (local-dir, cloud-file) warning below.
-      // Emit the same "manual reconciliation required" surface so the
-      // operator sees one consistent message for both topologies; record as
-      // skip-local-only so the file is not silently dropped from the
-      // count and the executor never tries to lstat/write it.
-      console.error(
-        `  Warning: an ancestor of ${remoteFile.key} exists locally as a regular file; ` +
-          `cloud has a deeper key under that path. Skipping; manual ` +
-          `reconciliation required (rm the conflicting local file to pull).`,
-      );
-      items.push({ action: "skip-local-only", remoteFile, localPath });
-      continue;
-    }
-
-    if (localExists) {
-      const isLocalSymlink = localLstat!.isSymbolicLink();
-      // Kind-mismatch guard: a remote LIST entry is always a single
-      // S3 object (regular file or symlink record), but the local
-      // path may be a real directory if the user previously had a
-      // dir at this key. Hashing a directory throws EISDIR and
-      // aborts the whole pull. We don't auto-replace because that
-      // would `rm -rf` the user's directory; surface as a non-fatal
-      // skip and warn so the operator can reconcile manually
-      // (delete the local dir, or restructure the remote).
-      if (localLstat!.isDirectory() && !isLocalSymlink) {
-        // Stale personal-overlay marker vs. release-shipped core directory:
-        // a single vault object at a `core/<overlay-type>/.../<entry>` key
-        // whose local counterpart is a real directory is an orphaned overlay
-        // symlink marker (reindex mirror artifact) left behind after a release
-        // shipped a real core dir of the same name. The local release-shipped
-        // directory is authoritative and the marker can never be materialized
-        // over it, so keep local and ignore the marker QUIETLY — the generic
-        // "rm -rf the local directory" advice below is actively dangerous here
-        // (it would destroy release-shipped core content to pull inert derived
-        // state), and it recurred on every sync. feedback_ce9aeede.
-        if (isGeneratedCoreMirrorKey(remoteFile.key)) {
-          console.error(
-            `  Note: ${remoteFile.key} is a stale personal-overlay marker ` +
-              `shadowing a release-shipped core directory; keeping the local ` +
-              `directory and ignoring the marker (no action needed).`,
-          );
-          items.push({
-            action: "skip-stale-overlay-marker",
-            remoteFile,
-            localPath,
-          });
-          continue;
-        }
-        // Directory-overlay marker vs. a locally-materialized directory:
-        // the remote object at this key carries CHILD objects under it in the
-        // same LIST (`remoteKeysWithChildren`), so it is a symlink/overlay
-        // record for a directory — e.g. the DPP vault's `skills/cody-copywriter`
-        // overlay whose 13 child objects are already materialized locally. The
-        // marker can never be renamed over the real directory, and its children
-        // carry the actual content and materialize via their own plan items, so
-        // the marker is a benign, no-action skip. The generic "rm -rf the local
-        // directory to pull" advice below would tell the operator to DELETE the
-        // materialized (and possibly locally-authored) contents to install an
-        // inert link, and it recurred on EVERY sync cycle. feedback_d2082110.
-        if (remoteKeysWithChildren.has(toPosixKey(remoteFile.key))) {
-          console.error(
-            `  Note: ${remoteFile.key} is a directory-overlay marker whose ` +
-              `contents already exist locally as a directory; keeping the ` +
-              `local directory and ignoring the marker (no action needed).`,
-          );
-          items.push({
-            action: "skip-overlay-marker-with-children",
-            remoteFile,
-            localPath,
-          });
-          continue;
-        }
-        console.error(
-          `  Warning: ${remoteFile.key} exists locally as a directory; ` +
-            `cloud has a single object at this key. Skipping; manual ` +
-            `reconciliation required (rm -rf the local directory to pull).`,
-        );
-        items.push({ action: "skip-local-only", remoteFile, localPath });
-        continue;
-      }
-      // Fast-path (5.36.0): when the journal entry has an mtimeMs and the
-      // local lstat matches both size and mtimeMs, the file hasn't been
-      // touched locally since the last sync, so we can reuse the journal's
-      // recorded hash without re-reading the file's bytes. Same shape as
-      // the share-side fast-path; only kicks in for regular files (symlink
-      // hashing through hashSymlinkTarget is already cheap — it hashes a
-      // short target string, not file bytes).
-      let localHash: string;
-      if (
-        !isLocalSymlink &&
-        journalEntry &&
-        journalEntry.mtimeMs !== undefined &&
-        journalEntry.hash &&
-        localLstat!.size === journalEntry.size &&
-        localLstat!.mtimeMs === journalEntry.mtimeMs
-      ) {
-        localHash = journalEntry.hash;
-      } else {
-        if (isLocalSymlink) {
-          const target = readlinkOrNull(localPath);
-          if (target === null) {
-            // We cannot prove whether the local link diverged, so never
-            // overwrite or tombstone it from this plan. A later pass can retry
-            // once the OS exposes a readable target.
-            items.push({ action: "skip-unreadable-link", remoteFile, localPath });
-            continue;
-          }
-          localHash = hashSymlinkTarget(target);
-        } else {
-          localHash = hashFile(localPath);
-        }
-      }
-      const localChanged = !!journalEntry && journalEntry.hash !== localHash;
-      plannedLocalSnapshot = {
-        kind: isLocalSymlink ? "symlink" : "file",
-        hash: localHash,
-      };
-      const remoteChanged =
-        !!journalEntry && hasRemoteChanged(remoteFile, journalEntry);
-
-      // ── Authoritative delete reaches a machine that still holds the file ──
-      // A FILE_TOMBSTONE marks this key deleted and the remote object is not a
-      // newer re-create, but this machine still has a local copy. Honor the
-      // delete — EXCEPT never destroy unsynced local work: if the local copy
-      // diverges from the synced baseline (a post-tombstone edit, or an
-      // untracked local file with no journal entry), surface a CONFLICT instead
-      // of silently deleting (the safety guard the brief requires + the 3-way
-      // merge invariant). A local copy that still matches the deleted baseline
-      // is the stale version → delete it + drop the journal entry so it stays
-      // gone on this machine.
-      if (tombstoneSuppresses) {
-        if (localChanged || !journalEntry) {
-          items.push({
-            action: "conflict",
-            remoteFile,
-            localPath,
-            localHash,
-            localMtime: localLstat!.mtime,
-            localSize: isLocalSymlink ? 0 : localLstat!.size,
-            localSnapshot: plannedLocalSnapshot,
-          });
-        } else {
-          items.push({
-            action: "tombstone-delete",
-            remoteFile,
-            localPath,
-            localSnapshot: plannedLocalSnapshot,
-          });
-        }
-        continue;
-      }
-
-      // ── Untracked-local guard (unjournaled local file) ──────────────
-      // Both `localChanged` and `remoteChanged` are gated on `!!journalEntry`,
-      // so a key with NO journal entry reads "clean on both sides" and falls
-      // all the way through to a plain `download` — silently replacing a local
-      // file that exists on disk. There is no conflict, no `.conflict-` mirror
-      // and no conflict-index record, so the loss is invisible unless someone
-      // happens to know what the file should contain.
-      //
-      // This destroyed in-progress edits to
-      // `companies/*/projects/*/prd.json` three times on 2026-08-01/02, but
-      // nothing about it is prd- or project-specific: it fires for ANY synced
-      // path whose journal entry is absent. Absence is common — a file created
-      // on this machine and on a peer under the same key before either pushed,
-      // a journal shard reset/lost/rebuilt (`readJournal` returns an empty
-      // `files` map for a missing shard, so EVERY divergent local file is in
-      // scope), a run under a different `HQ_STATE_DIR`, or an entry dropped by
-      // scope-shrink or rescue.
-      //
-      // No journal entry means no evidence that local and remote ever agreed,
-      // which is exactly when an overwrite is least safe. Route it through the
-      // conflict path instead: the executor's convergence probe fetches the
-      // remote once and, when the bytes already match (the ordinary
-      // fresh-machine / rebuilt-journal case), reconciles silently — no
-      // conflict, no mirror, journal stamped. Only genuine divergence surfaces,
-      // and there local is PRESERVED as-is with the cloud copy written beside
-      // it under `--on-conflict keep`, or the run halts under `abort`.
-      // Cloud-authoritative paths (board.json, ontology/, signals/, …) are
-      // unaffected — the conflict executor short-circuits those back to a
-      // pull-wins download before any mirror is minted.
-      if (!journalEntry) {
-        items.push({
-          action: "conflict",
-          remoteFile,
-          localPath,
-          localHash,
-          localMtime: localLstat!.mtime,
-          localSize: isLocalSymlink ? 0 : localLstat!.size,
-          localSnapshot: plannedLocalSnapshot,
-        });
-        continue;
-      }
-
-      // Mirror the original 3-way merge from the inline loop. Tested by
-      // `does NOT flag a pull conflict when only local changed since last
-      // sync` and `detects conflicts with local changes…`.
-      if (localChanged && remoteChanged) {
-        items.push({
-          action: "conflict",
-          remoteFile,
-          localPath,
-          localHash,
-          // localLstat is non-null inside this `if (localExists)`
-          // branch — the planner already lstat'd the path. Carry
-          // its mtime forward so the executor doesn't have to
-          // re-stat (which would follow links and crash on a
-          // dangling symlink). Same goes for size: the conflict
-          // executor's keep/skip branch needs to stamp the
-          // journal with a size, and statSync on a dangling
-          // symlink throws ENOENT (silently swallowed pre-fix),
-          // leaving the journal stale and re-firing the conflict
-          // every sync.
-          localMtime: localLstat!.mtime,
-          localSize: isLocalSymlink ? 0 : localLstat!.size,
-          localSnapshot: plannedLocalSnapshot,
-        });
-        continue;
-      }
-      if (journalEntry && localChanged && !remoteChanged) {
-        items.push({ action: "skip-local-only", remoteFile, localPath });
-        continue;
-      }
-      if (journalEntry && !localChanged && !remoteChanged) {
-        // Flavor-health repair (win32 skill farm): a link journaled while its
-        // target was absent was minted file-flavor; once the target directory
-        // exists the hashes still match (hash = sha256(target)) so this
-        // branch would skip it forever, leaving the wrapper broken. Re-download
-        // instead — the materializer's flavor-aware path recreates it 'dir'.
-        if (
-          isLocalSymlink &&
-          remoteFile.key.startsWith(SKILLS_KEY_PREFIX) &&
-          win32SymlinkFlavorBroken(localPath)
-        ) {
-          items.push({
-            action: "download",
-            remoteFile,
-            localPath,
-            isNew: false,
-            localSnapshot: plannedLocalSnapshot,
-          });
-          continue;
-        }
-        items.push({ action: "skip-unchanged", remoteFile, localPath });
-        continue;
-      }
-      if (journalEntry && !localChanged && remoteChanged) {
-        // ── Anti-rollback guard (silent newer→older overwrite) ───────────
-        // Remote etag moved but local still matches the journal baseline, so
-        // the classic 3-way merge calls this a clean `download` and overwrites
-        // local with remote. That assumes the remote *advanced*. It can also
-        // REGRESS: a second device (or a stale re-push) can replace the S3
-        // object with an OLDER, SMALLER copy. `hasRemoteChanged` is pure-ETag
-        // and cannot tell an advance from a rollback — ListObjectsV2 carries no
-        // content hash, and `lastModified` is the upload time (newer even for
-        // stale content), so neither distinguishes the two. A silent download
-        // then DESTROYS newer local bytes with no conflict surfaced.
-        //
-        // This bit append-only bot chat logs on 2026-06-10, the day
-        // event-driven bidirectional sync (which lets a peer device push to
-        // S3 between this device's pulls) first rolled out: a regressed S3
-        // object truncated freshly-appended lines, undetected by the planner.
-        //
-        // Guard: if the incoming remote object is strictly SMALLER than the
-        // local file we already hold (a size regression on a tracked regular
-        // file), do NOT silently clobber. Route through the conflict path —
-        // the executor's convergence probe fetches the remote once and, on
-        // genuine divergence, PRESERVES local as a `.conflict-*` mirror instead
-        // of overwriting it (and under `--on-conflict abort` halts loudly
-        // rather than losing data). A byte-identical remote can never be
-        // smaller, so this never manufactures a false conflict on a no-op
-        // re-upload. Symlinks are exempt: their on-disk size is not the target
-        // length, so the comparison is meaningless.
-        //
-        // Direction gate: only guard copies this device AUTHORED (last synced
-        // UP). A consumer copy (last synced DOWN) has no local authorship to
-        // protect — the remote is authoritative, so a smaller remote is a
-        // legitimate update (e.g. the gardener rewriting a shorter brief), not a
-        // regression. Without this gate a consumer device floods `.conflict`
-        // mirrors and stalls on stale gardener output forever (the 786-file
-        // pile-up, 2026-06-22). `"up"` and any missing/unknown direction stay
-        // guarded exactly as before — the 2026-06-10 chat-log protection holds.
-        if (
-          journalEntry.direction !== "down" &&
-          !isLocalSymlink &&
-          remoteFile.size < localLstat!.size
-        ) {
-          items.push({
-            action: "conflict",
-            remoteFile,
-            localPath,
-            localHash,
-            localMtime: localLstat!.mtime,
-            localSize: localLstat!.size,
-            localSnapshot: plannedLocalSnapshot,
-          });
-          continue;
-        }
-        // Remote genuinely advanced (same-or-larger) → normal catch-up
-        // download below.
-      }
-      // No journal entry, or remote-only changed (non-shrinking) → fall
-      // through to download.
-    }
-
-    // Suppress the re-download of an intentionally-deleted key (delete-resync).
-    // Reaches here only for the `!localExists` case — the `localExists` branch
-    // above already handled (and `continue`d) any suppressing tombstone, so a
-    // tombstone that survives to here means "remote present, local absent, not a
-    // re-create": the classic resurrection ("remote present → I'm behind →
-    // download") the planner must NOT do. Route to `tombstone-delete` so the
-    // executor drops any stale journal entry and the key stays gone, instead of
-    // pulling the deleted object back in. `localTombstoneSuppresses` adds the
-    // same protection driven by this machine's own journal tombstone, so an
-    // intentional delete is not resurrected even when the server FILE_TOMBSTONE
-    // fetch is degraded.
-    if (tombstoneSuppresses || localTombstoneSuppresses) {
-      // A persisting `local-delete` tombstone (stamped by the intentional-delete
-      // producer below) must KEEP its journal entry — the push leg still needs
-      // it to propagate the S3 delete. Skip the re-download without dropping the
-      // entry. Other tombstone kinds (scope-shrink / FILE_TOMBSTONE) drop it.
-      if (journalEntry?.removedReason === "local-delete") {
-        continue;
-      }
-      items.push({
-        action: "tombstone-delete",
-        remoteFile,
-        localPath,
-        localSnapshot: plannedLocalSnapshot,
-      });
-      continue;
-    }
-
-    // Intentional-delete producer: a clean, CURRENT (etag matches), non-divergent
-    // file that is MISSING locally is the user deleting a genuinely-synced file.
-    // Collect it; the post-loop bulk-asymmetry decision tombstones it (intent) or
-    // restores it (mass loss = accident). A stale-etag, divergent, tombstoned, or
-    // never-journaled missing file falls through to the normal download below.
-    if (
-      !localExists &&
-      journalEntry !== undefined &&
-      !isTombstone(journalEntry) &&
-      hasCurrentLocalDeleteIntent(journalEntry) &&
-      normalizeEtag(remoteFile.etag) === journalEntry.remoteEtag
-    ) {
-      intentionalDeleteCandidates.push({ remoteFile, localPath });
-      continue;
-    }
-
-    items.push({
-      action: "download",
-      remoteFile,
-      localPath,
-      isNew: !localExists,
-      localSnapshot: plannedLocalSnapshot,
-    });
-  }
-
-  // ── Intentional-delete bulk-asymmetry decision (pull-leg producer) ─────────
-  // Below the breaker → stamp a persisting `local-delete` tombstone (the
-  // suppression above keeps it from being re-pulled; the push leg propagates the
-  // S3 delete on its next pass). At/above → drift-restore EVERY candidate: a
-  // mass disappearance (corrupt mirror / bulk rm / checkout / unmount) is
-  // accidental loss, never intent (the ridge-incident guard).
-  const totalJournalEntries = Object.keys(journal.files).length;
-  const intentionalDeleteIsBulk =
-    intentionalDeleteCandidates.length >= PULL_INTENTIONAL_DELETE_MIN_ABS &&
-    totalJournalEntries > 0 &&
-    intentionalDeleteCandidates.length / totalJournalEntries >=
-      PULL_INTENTIONAL_DELETE_RATIO;
-  for (const cand of intentionalDeleteCandidates) {
-    if (intentionalDeleteIsBulk) {
-      items.push({
-        action: "download",
-        remoteFile: cand.remoteFile,
-        localPath: cand.localPath,
-        isNew: true,
-        localSnapshot: { kind: "absent" },
-      });
-    } else {
-      tombstoneEntry(journal, cand.remoteFile.key, "local-delete");
-    }
-  }
-
-  let filesToDownload = 0;
-  let bytesToDownload = 0;
-  let filesToSkip = 0;
-  let filesToConflict = 0;
-  let filesExcludedByPolicy = 0;
-  let filesOutOfScope = 0;
-  let filesToTombstoneDelete = 0;
-  const newFiles: Array<{ path: string; bytes: number }> = [];
-  for (const item of items) {
-    if (item.action === "download") {
-      filesToDownload++;
-      bytesToDownload += item.remoteFile.size;
-      if (item.isNew) {
-        newFiles.push({ path: item.remoteFile.key, bytes: item.remoteFile.size });
-      }
-    } else if (item.action === "conflict") {
-      filesToConflict++;
-    } else if (item.action === "tombstone-delete") {
-      // Authoritative FILE_TOMBSTONE delete — its own axis so it never inflates
-      // the "unchanged" tally. Surfaced via the plan event's filesToDelete.
-      filesToTombstoneDelete++;
-    } else if (item.action === "skip-excluded-policy") {
-      filesExcludedByPolicy++;
-      // Excluded-policy items don't roll into filesToSkip — they're a
-      // distinct class surfaced via filesExcludedByPolicy so consumers
-      // can render a "N refused by policy" line independently of the
-      // generic "N unchanged" tally.
-    } else if (item.action === "skip-out-of-scope") {
-      // Out-of-scope items get their own axis too, mirroring excluded-policy:
-      // they're "deliberately not downloaded (sync scope)", not "unchanged".
-      filesOutOfScope++;
-    } else {
-      filesToSkip++;
-    }
-  }
-
-  // Bug #9 — cross-machine delete propagation. The peer's push leg
-  // already removed the file from S3 (verified in the deep-test
-  // addendum: `aws s3 ls` showed the keys absent post-push). Pre-fix
-  // the pull side enumerated remote keys and downloaded anything
-  // missing locally, but never enumerated "what's missing-from-remote-
-  // that-was-there-before" — so the file stayed forever on every
-  // receiver and `filesTombstoned: 0` showed up on every pull.
-  //
-  // Closing the loop: walk the journal, find every entry whose key is
-  // NOT in the remote LIST set, AND whose path passes the current
-  // ignore filter (paths newly excluded by .hqignore must not trigger
-  // mass-delete), AND — in personalMode — survives the same companies/*
-  // gating the download branch applies. The executor will apply each
-  // as a local delete + journal removal. Symmetric to the push side's
-  // `propagateDeletes` plan in share.ts.
-  const remoteKeySet = new Set<string>();
-  // Skill-farm twin protection (companion to the junk-spelling pull guard):
-  // when the LIST holds only a junk spelling of a journaled canonical key,
-  // the logical object is still remotely present — a raw has() would class
-  // the canonical journal entry as remote-deleted, unlink the good local
-  // wrapper, and drop the journal entry (after which the next pull would
-  // materialize the junk spelling the guard just refused). Track canonical
-  // forms of listed skill keys and consult them below.
-  const remoteCanonicalSkillKeys = new Set<string>();
-  for (const rf of remoteFiles) {
-    remoteKeySet.add(rf.key);
-    if (rf.key.startsWith(SKILLS_KEY_PREFIX)) {
-      remoteCanonicalSkillKeys.add(canonicalVaultKeySpelling(rf.key));
-    }
-  }
-  const tombstones: PullPlan["tombstones"] = [];
-  for (const key of Object.keys(journal.files)) {
-    // Compare membership in POSIX space. A pre-5.47.2 Windows journal key can
-    // carry backslash separators; the remote LIST is always forward-slash, so a
-    // raw `has(key)` would miss the match and class a live local file as
-    // remote-deleted. normalizeJournalKeys() defuses this on load, but the
-    // POSIX compare is defense-in-depth (ridge data-loss, feedback_b8d09d0f).
-    const posixKey = toPosixKey(key);
-    if (remoteKeySet.has(posixKey)) continue;
-    if (
-      posixKey.startsWith(SKILLS_KEY_PREFIX) &&
-      remoteCanonicalSkillKeys.has(canonicalVaultKeySpelling(posixKey)) &&
-      // An EXACT FILE_TOMBSTONE for the journaled key is an authoritative
-      // delete and wins over the twin protection — a lingering junk
-      // spelling in the LIST must not keep a deliberately-deleted wrapper
-      // alive forever. (The key is absent from the LIST here, so there is
-      // no newer re-create to defer to.)
-      fileTombstones.get(posixKey) === undefined
-    ) {
-      continue;
-    }
-    const localPath = resolveContainedVaultPath(companyRoot, key);
-    if (localPath === null) continue;
-    // Scope-invalid journal keys (company mode, `companies/…` prefix): the
-    // download branch skips them (presign rejects), but a journaled entry whose
-    // key is absent from the remote LIST is doubled-tree poison that must
-    // drain — local copy under companies/{slug}/companies/{slug}/… removed and
-    // journal dropped. HEAD verify is skipped in verifyPlannedJournalTombstones
-    // (presign would reject); see the auto-verified branch there.
-    const scopeInvalidJournalKey = isForbiddenCompanyVaultKey(key, personalMode);
-    // PersonalMode key gating — mirror the download branch. Local (non-cloud)
-    // company keys are tombstone-eligible (a peer's delete should propagate),
-    // but team-synced orphans are left alone (the team-bucket pull owns those
-    // disk paths), and the manifest — the routing source-of-truth — is never
-    // auto-tombstoned out of the personal vault.
-    if (personalMode && key.startsWith("companies/")) {
-      const slug = key.split("/")[1] ?? "";
-      const isTeamSyncedOrphan =
-        teamSyncedSlugs !== null && slug !== "" && teamSyncedSlugs.has(slug);
-      if (isTeamSyncedOrphan || key === PERSONAL_VAULT_MANIFEST_KEY) continue;
-    }
-    // Ephemeral keys are filtered both directions; never tombstone-
-    // propagate a conflict-mirror.
-    if (isEphemeralPath(key)) continue;
-    // Honor the current ignore filter — if a path was previously synced
-    // but is now ignored (operator edited .hqignore), do NOT delete
-    // the local copy. They're keeping it deliberately. Scope-invalid poison
-    // bypasses this: the doubled-tree copy must not survive silently.
-    if (
-      !scopeInvalidJournalKey &&
-      !shouldSync(localPath, false) &&
-      !shouldSync(localPath, true)
-    ) {
-      continue;
-    }
-    // Codex P1 (PR #24 round 3): detect local edits before tombstoning.
-    // Delete-vs-local-edit race: peer deleted the file remotely while
-    // this machine edited it locally before the next sync. Without
-    // this check, the tombstone executor would unlink the locally-
-    // edited file and drop the journal entry, silently destroying the
-    // user's unsynced work. Compare local hash against the journal
-    // baseline; if they diverge, defer the tombstone. The next pull
-    // run after the operator resolves (re-pushes / overwrites) the
-    // local state will re-evaluate.
-    try {
-      const lstat = fs.lstatSync(localPath);
-      if (lstat.isFile()) {
-        const localHash = hashFile(localPath);
-        const journalEntry = journal.files[key];
-        if (journalEntry?.hash && journalEntry.hash !== localHash) {
-          // Local has unsynced edits — defer this tombstone.
-          continue;
-        }
-      } else if (lstat.isSymbolicLink()) {
-        // Codex P1 (PR #24 round 4): symlinks have target strings
-        // that can be locally edited too. Pre-fix, `isFile()` was
-        // false for symlinks so the divergence guard skipped them,
-        // and a locally-edited symlink (`ln -sfn new-target old-link`
-        // before the peer's remote-delete) was unlinked silently —
-        // the exact race the guard is meant to prevent. Compare the
-        // readlink hash against the journal baseline; defer on
-        // divergence. readlink errors (race / EACCES) also defer.
-        try {
-          const localHash = hashSymlinkTarget(fs.readlinkSync(localPath));
-          const journalEntry = journal.files[key];
-          if (journalEntry?.hash && journalEntry.hash !== localHash) {
-            continue;
-          }
-        } catch {
-          continue;
-        }
-      }
-      // Directories: no hash comparison. The tombstone executor's
-      // dir branch doesn't recursively rm-rf — it just drops the
-      // journal entry, which is the safe-by-default behavior.
-    } catch (err) {
-      const code =
-        err && typeof err === "object" && "code" in err
-          ? (err as { code?: string }).code
-          : undefined;
-      // ENOENT → local already gone; safe to drop journal entry via
-      // the executor's tombstone path.
-      // Other lstat errors (EACCES on parent dir, etc.) → defer:
-      // we can't read local state, so we can't safely decide.
-      if (code !== "ENOENT") continue;
-    }
-    const localSnapshot = snapshotLocalState(localPath);
-    if (localSnapshot === null) continue;
-    tombstones.push({ key, localPath, localSnapshot });
-  }
-
-  return {
-    items,
-    filesToDownload,
-    bytesToDownload,
-    filesToSkip,
-    filesToConflict,
-    newFiles,
-    newFilesCount: newFiles.length,
-    filesExcludedByPolicy,
-    filesOutOfScope,
-    filesToTombstoneDelete,
-    tombstones,
-    invalidRemoteKeys,
-  };
-}
-
-/**
- * Default human-readable event rendering. Preserves the exact output format
- * that `hq sync` emitted before SyncProgressEvent was introduced, so callers
- * without an `onEvent` see no behavioral change.
- */
-function defaultConsoleLogger(event: SyncProgressEvent): void {
-  if (event.type === "plan") {
-    // Terse single line so humans see what's about to happen without
-    // drowning the per-file output that follows. Skip when there's
-    // nothing to do — no signal, no noise.
-    const movement = event.filesToDownload + event.filesToUpload + event.filesToConflict;
-    if (movement > 0) {
-      const parts: string[] = [];
-      if (event.filesToDownload > 0) {
-        parts.push(`${event.filesToDownload} to download (${event.bytesToDownload} bytes)`);
-      }
-      if (event.filesToUpload > 0) {
-        parts.push(`${event.filesToUpload} to upload (${event.bytesToUpload} bytes)`);
-      }
-      if (event.filesToConflict > 0) {
-        parts.push(`${event.filesToConflict} conflict(s)`);
-      }
-      parts.push(`${event.filesToSkip} unchanged`);
-      console.log(`Plan: ${parts.join(", ")}`);
-    }
-  } else if (event.type === "progress") {
-    if (event.message) {
-      console.log(`  ✓ ${event.path} — "${event.message}"`);
-    } else {
-      console.log(`  ✓ ${event.path}`);
-    }
-  } else if (event.type === "error") {
-    console.error(`  ✗ ${event.path} — ${event.message}`);
-  } else if (event.type === "conflict") {
-    console.error(
-      `  ⚠ conflict (${event.direction}): ${event.path} — ${event.resolution}`,
-    );
-  } else if (event.type === "reconciled") {
-    console.log(
-      `  = reconciled (${event.direction}): ${event.path} — remote bytes identical to local, journal re-stamped`,
-    );
-  } else if (event.type === "new-files") {
-    if (event.files.length > 0) {
-      console.log(`${event.files.length} new file${event.files.length === 1 ? "" : "s"}`);
-      const MAX_SHOWN = 20;
-      const shown = event.files.slice(0, MAX_SHOWN);
-      for (const f of shown) {
-        const who = f.addedBy ? ` (added by ${f.addedBy})` : "";
-        console.log(`  + ${f.path}${who}`);
-      }
-      if (event.files.length > MAX_SHOWN) {
-        console.log(`  ... and ${event.files.length - MAX_SHOWN} more`);
-      }
-    }
-  } else if (event.type === "scope-excluded") {
-    console.log(
-      `  ~ ${event.count} path${event.count === 1 ? "" : "s"} skipped — outside your granted access (synced the in-scope subset):`,
-    );
-    for (const p of event.samplePaths) {
-      console.log(`    · ${p}`);
-    }
-    if (event.count > event.samplePaths.length) {
-      console.log(`    ... and ${event.count - event.samplePaths.length} more`);
-    }
-  } else if (event.type === "scope-materialization-gap") {
-    console.warn(
-      `  ! ${event.count} item${event.count === 1 ? "" : "s"} in this vault did NOT sync to this device — your access level is "${event.syncMode}", so only shared paths materialize. To pull everything you have access to, set this membership's access level to "all":`,
-    );
-    for (const p of event.samplePaths) {
-      console.warn(`    · ${p}`);
-    }
-    if (event.count > event.samplePaths.length) {
-      console.warn(`    ... and ${event.count - event.samplePaths.length} more`);
-    }
-  } else if (event.type === "ignore-excluded") {
-    console.warn(
-      `  ! ${event.count} path${event.count === 1 ? "" : "s"} were EXCLUDED from sync by an ignore rule and did NOT reach the vault (review in case this is unintended):`,
-    );
-    for (const p of event.samplePaths) {
-      console.warn(`    · ${p}`);
-    }
-    if (event.count > event.samplePaths.length) {
-      console.warn(`    ... and ${event.count - event.samplePaths.length} more`);
-    }
-  } else if (event.type === "skip-size-limit") {
-    const mb = (event.bytes / (1024 * 1024)).toFixed(1);
-    console.warn(
-      `  ! ${event.path} skipped — ${mb} MB exceeds the 50 MB sync size limit`,
-    );
-  } else if (event.type === "skip-invalid-scoped-key") {
-    console.warn(
-      `  ! ${event.path} skipped — invalid vault key (${event.errorCode ?? "INVALID_KEY_COMPANIES_SCOPED"})`,
-    );
-  } else if (event.type === "skip-junk-key-spelling") {
-    console.warn(
-      `  ! ${event.path} skipped — junk key spelling; this logical path is already synced as ${event.journaledKey} (mixed-version peer artifact; the vault doctor collapses the family)`,
-    );
-  } else if (event.type === "not-shipped") {
-    if (event.reason === "unreachable-path") {
-      console.warn(
-        `  ! ${event.count} named path${event.count === 1 ? "" : "s"} could NOT be pushed — the file exists but is not reachable under the company folder (nothing was uploaded for ${event.count === 1 ? "it" : "them"}):`,
-      );
-    } else if (event.reason === "unreadable-link") {
-      console.warn(
-        `  ! ${event.count} symbolic link${event.count === 1 ? "" : "s"} could NOT be read and was skipped without dereferencing its target:`,
-      );
-    } else {
-      console.warn(
-        `  ! ${event.count} linked subtree${event.count === 1 ? "" : "s"} recorded but NOT uploaded — contents sync via their own repo, not the vault:`,
-      );
-    }
-    for (const p of event.samplePaths) {
-      console.warn(`    · ${p}`);
-    }
-    if (event.count > event.samplePaths.length) {
-      console.warn(`    ... and ${event.count - event.samplePaths.length} more`);
-    }
-    if (event.reason === "linked-subtree") {
-      console.warn(
-        `    To put a file from a linked subtree in the vault, push it by name:\n` +
-        `      hq sync push <path> --company <slug>\n` +
-        `    That uploads a point-in-time copy; re-run it after each edit (regular sync will not track or update it).`,
-      );
-    }
-  }
-}