@indigoai-us/hq-cloud 6.15.0 → 6.15.1

package/src/cli/share.ts

@@ -1,3663 +0,0 @@
-/**
- * `hq share` command — selective push to entity vault (VLT-5 US-002).
- *
- * Broadcasts local file(s) to the company's S3 vault bucket.
- * Refuses to overwrite a newer remote version without prompting.
- */
-
-import * as fs from "fs";
-import * as os from "os";
-import * as path from "path";
-import type { EntityContext, VaultServiceConfig, SyncJournal } from "../types.js";
-import { resolveEntityContext, isExpiringSoon, refreshEntityContext } from "../context.js";
-import { createSyncProgressRecorder } from "../sync-progress.js";
-import { localPathForVaultKey, vaultKeyForLocalPath } from "../local-path-codec.js";
-import {
-  uploadFile,
-  uploadSymlink,
-  toPosixKey,
-  headRemoteFile,
-  deleteRemoteFile,
-  downloadFile,
-  primeObjectTransport,
-  primeUploads,
-} from "../s3.js";
-import * as crypto from "crypto";
-import type { UploadAuthor } from "../s3.js";
-import type { PutPrecondition } from "../object-io.js";
-import {
-  readJournal,
-  writeJournal,
-  hashFile,
-  hashSymlinkTarget,
-  updateEntry,
-  removeEntry,
-  isTombstone,
-  normalizeEtag,
-  PERSONAL_VAULT_JOURNAL_SLUG,
-  migratePersonalVaultJournal,
-} from "../journal.js";
-import {
-  createIgnoreFilter,
-  hasControlCharacters,
-  isExpectedIgnore,
-  isWithinSizeLimit,
-} from "../ignore.js";
-import {
-  wrapFilterWithPersonalVaultDefaults,
-  type PersonalVaultExclusion,
-} from "../personal-vault-exclusions.js";
-import {
-  isGeneratedCoreMirrorKey,
-  isPersonalVaultDeletionExcluded,
-} from "../personal-vault.js";
-import { resolveConflict } from "./conflict.js";
-import type { ConflictStrategy } from "./conflict.js";
-import type { SyncProgressEvent } from "./sync.js";
-import {
-  fetchCompanyTombstones,
-  type CompanyTombstone,
-} from "./tombstones.js";
-import {
-  isCoveredByAny,
-  isDirInScope,
-  type ScopePrefixInput,
-} from "../prefix-coalesce.js";
-import {
-  hasRemoteChanged,
-  isAccessDenied,
-  resolveActiveCompany,
-  resolveTransferConcurrency,
-} from "../sync-core.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 { VaultAuthError } from "../vault-client.js";
-import { describeError } from "../lib/describe-error.js";
-import { readlinkOrNull } from "../lib/readlink-safe.js";
-
-/**
- * Push-side fresh-collision convergence probe.
- *
- * For a first push (no journal entry) where the remote object already
- * exists, its etag is a version token rather than a reliable content hash,
- * so we cannot tell "byte-identical" from "genuine divergence" without
- * looking at the bytes. Fetch the remote object once to a throwaway temp
- * file, hash it the same symlink-aware way the planner hashed local, and
- * report whether the two contents DIFFER.
- *
- * Returns `true` on a genuine difference (a real fresh collision) and
- * `false` when the bytes are identical. Fails safe to `true` on any
- * fetch/hash error — a false positive merely prompts the operator, while a
- * false negative could silently clobber a peer's content. Mirrors the
- * pull-side convergence guard in `sync.ts`.
- *
- * The temp file lives in the OS temp dir (never under hqRoot) so it can
- * never round-trip to S3, and is removed in a `finally` regardless of
- * outcome. The name is derived from the relative path so concurrent probes
- * for distinct files never collide on disk.
- */
-async function remoteContentDiffers(
-  ctx: EntityContext,
-  relativePath: string,
-  localHash: string,
-  hqRoot: string,
-): Promise<boolean> {
-  const probeKey = crypto
-    .createHash("sha256")
-    .update(relativePath)
-    .digest("hex")
-    .slice(0, 16);
-  const probePath = path.join(
-    os.tmpdir(),
-    `hq-conflict-probe-${readShortMachineId(hqRoot)}-${probeKey}.tmp`,
-  );
-  try {
-    await downloadFile(ctx, relativePath, probePath);
-    const remoteHash = fs.lstatSync(probePath).isSymbolicLink()
-      ? hashSymlinkTarget(fs.readlinkSync(probePath))
-      : hashFile(probePath);
-    return remoteHash !== localHash;
-  } catch (err) {
-    if (err instanceof VaultAuthError) throw err;
-    return true;
-  } finally {
-    try {
-      fs.rmSync(probePath, { force: true });
-    } catch {
-      /* best-effort cleanup; a stray temp probe is harmless */
-    }
-  }
-}
-
-/**
- * Local-only ephemeral artifacts: conflict-mirror files written by the pull
- * leg whenever a 3-way merge keeps local AND wants to preserve the remote
- * version for inspection. Format: `<orig>.conflict-<ISO-utc>-<machineHash>[.ext]`
- * (e.g. `.claude/CLAUDE.md.conflict-2026-05-13T19-40-40Z-e5797a.md`,
- * or `.gitignore.conflict-2026-05-13T19-40-40Z-e5797a` — extensionless
- * originals produce no trailing dot, see `buildConflictPath` in
- * `../lib/conflict-file.ts`).
- *
- * These files MUST never round-trip to S3 — they're local-only safety backups
- * the user reviews and deletes once the merge is resolved. Pre-fix, the push
- * walker happily uploaded them, the journal recorded them, and the
- * `owned-only` delete policy then refused to clean them up when the user
- * deleted them locally (because pull-confirmation had stamped them as
- * `direction: "down"`). Net effect: a permanent litter ratchet on remote.
- *
- * Two known producer-shapes the regex must accommodate (both observed on
- * affected user trees prior to this fix):
- *
- *   1. **`unknown` machine token.** Pre-`<hqRoot>/.hq/machine-id`
- *      provisioning (see `../lib/machine-id.ts`), hosts without
- *      `~/.hq/menubar.json` — every Linux HQ Pro Outpost, every fresh CLI
- *      install — fell through to the literal string `"unknown"` from the
- *      old `readShortMachineId()` fallback. The letters `k`, `n`, `o`, `w`
- *      live outside `[a-f]`, so the pre-fix `[a-f0-9]+` class refused those
- *      filenames. They round-tripped to S3 as ordinary files (which IS the
- *      "permanent litter ratchet" this module's contract was supposed to
- *      prevent). The new machine-id provisioning closes the producer side,
- *      but we still accept `unknown` here so legacy files already on disk
- *      are filtered out by the next push.
- *
- *   2. **Extensionless originals.** `path.extname('.gitignore')` returns
- *      `''` in Node, so `buildConflictPath` produces no trailing `.<ext>`
- *      segment for hidden-but-extensionless files like `.gitignore`,
- *      `.hqignore`, or any `.agents/skills`-style entry. The pre-fix `\.`
- *      tail was mandatory, so those names slipped through.
- *
- * Wire-points: (1) push walker — `collectFiles` / `walkDir` skip these so
- * they never upload; (2) `computeDeletePlan` — skip these so an already-
- * journaled mirror that's been deleted locally doesn't get included in the
- * regular delete plan (the dedicated reconcile path handles existing litter).
- */
-export const EPHEMERAL_PATH_PATTERN =
-  /\.conflict-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z-(?:[a-f0-9]+|unknown)(?:\.[^/]*)?$/;
-
-/**
- * Cheap pure check — pass the relative key OR a basename; either works. Used
- * in both the file walker (basename matching) and the delete-plan walker
- * (relative-key matching), and also by the pull walker in sync.ts to refuse
- * downloading legacy conflict-mirror files that still live in cloud staging
- * (Bug #2 in the 5.33.0 deep-test report — push-side filtered them since
- * 5.33.0 but pull-side downloaded them freely until this export). The regex
- * matches anywhere in the string, which is fine: the
- * `.conflict-<ISO>-<hash>.` token is unambiguous.
- */
-/**
- * Rescue-overlay drift marker pattern. Written by `replace-rescue.sh`
- * (`rescue_one` / `conflict_one`) when its rescue target already exists:
- * `<orig>.drift-<unix-ts>-<pid>` — a collision suffix so the previous override
- * is never silently overwritten. Distinct from `EPHEMERAL_PATH_PATTERN` —
- * different producer (the rescue script vs the sync conflict-mirror path),
- * different filename grammar (decimal timestamp + decimal pid vs ISO timestamp
- * + hex machine hash). Like conflict mirrors, drift markers should never live
- * in the vault; if a buggy past run uploaded one, the delete plan must be
- * able to drain it regardless of where it sits.
- */
-export const DRIFT_PATH_PATTERN = /\.drift-\d+-\d+$/;
-
-/**
- * True iff the key is local-only ephemeral vault litter — a sync conflict
- * mirror (`.conflict-<ISO>-<machine>[.ext]`) OR a rescue drift marker
- * (`.drift-<unixts>-<pid>`).
- *
- * Used by `computeDeletePlan` to UNCONDITIONALLY drain existing vault litter,
- * bypassing every "skip" gate that would otherwise trap it:
- *
- *   1. `shouldSync` — the personal-vault default exclusions (introduced in
- *      5.25) reject paths like `**.obsidian/**`, `**.env`, `**output/**`,
- *      `**node_modules/**`, etc. from BOTH the upload walk AND the delete
- *      plan. That's correct for fresh content (don't upload), but it also
- *      strands any litter already in the vault at those paths — `<orig>.drift`
- *      / `<orig>.conflict` files inside an excluded parent get re-pulled
- *      every sync and never tombstoned. The live obsidian case here:
- *      `personal/.obsidian/graph.json.drift-1779863862-42519` survived every
- *      sync for two weeks because `.obsidian` is excluded.
- *   2. `isEphemeralPath` — the existing skip in `computeDeletePlan` was
- *      designed to prevent a FRESH local `.conflict-*` mirror (written by the
- *      pull leg's "keep" branch as a side-by-side comparison file) from being
- *      miscounted as a delete candidate before the user has resolved the
- *      conflict. That intent stands, but it accidentally protects EXISTING
- *      cloud litter too. The fix: when the local file is already gone AND the
- *      key matches the litter pattern, drain it; the "fresh mirror, hasn't
- *      been resolved yet" case is impossible because that mirror would still
- *      be on disk.
- *   3. The policy gate — `owned-only`'s direction filter and
- *      `currency-gated`'s etag check both encode user-content invariants
- *      that don't apply to litter (a `.drift-…-PID` file has no meaningful
- *      "ownership" or "freshness"; it's a stale local-overlay collision
- *      marker, by construction).
- *   4. The bulk-asymmetry circuit breaker — litter cleanup is intentional
- *      ratchet-drain, not a "corrupt local mirror, refuse mass-delete"
- *      signal. Litter is queued via a separate bucket the breaker never
- *      sweeps.
- *
- * Together: a vault key matching either pattern always tombstones on the
- * next push leg, regardless of personal-vault exclusions, ephemeral skip,
- * policy, or breaker. Producer-side exclusions (upload walker + rescue
- * script) close the ratchet on new litter; this drains the legacy buildup.
- */
-export function isVaultLitterArtifact(p: string): boolean {
-  return EPHEMERAL_PATH_PATTERN.test(p) || DRIFT_PATH_PATTERN.test(p);
-}
-
-export function isEphemeralPath(p: string): boolean {
-  return EPHEMERAL_PATH_PATTERN.test(p);
-}
-
-/**
- * A vault key containing a backslash is never legitimate. HQ keys are POSIX
- * (`toPosixKey` normalizes at every walker since 5.47.2 and `uploadFile`
- * hard-normalizes at the S3 boundary), so a `\` in a remote key can only come
- * from a pre-5.47.2 Windows client whose walker built keys with `path.sep` —
- * verified live 2026-06-10: one such client duplicated 5,711 keys
- * (`skills\demo-hq\SKILL.md`, …) into a company vault, and every up-to-date
- * puller then materialized them as junk single-filename-with-backslash files
- * that churned conflicts forever. The pull walker refuses these keys
- * (skip-excluded-policy), symmetric with the ephemeral-mirror filter above.
- */
-export function isMalformedVaultKey(key: string): boolean {
-  return key.includes("\\");
-}
-
-/**
- * A remote key that begins with `companies/<slug>/` is legitimate ONLY in a
- * PERSONAL vault, where it is handled by the dedicated `personalMode` branch
- * in `computePullPlan` (companies/* content a peer machine pushed into the
- * personal bucket). A COMPANY-scoped vault is already anchored at its company
- * root, so its keys are bucket-relative — a `companies/...` key there is a
- * doubly-scoped corrupt object. The vault-service refuses to presign such a
- * key on GET/HEAD with `INVALID_KEY_COMPANIES_SCOPED`, so the puller can
- * never materialize it and the whole company sync wedges at `errored` (runner
- * exit 2) on every run. Verified live 2026-06-16: frogbear's
- * `companies/frogbear/drafts/reports/frogbear-signals-report-2026-06-15.html`
- * was uploaded with a doubled key and broke every sync thereafter. The pull
- * and tombstone walkers refuse these keys (skip-excluded-policy), symmetric
- * with the malformed-(backslash)-key filter above; the bogus objects
- * themselves are cleaned server-side.
- */
-export function isForbiddenCompanyVaultKey(key: string, personalMode: boolean): boolean {
-  return !personalMode && key.startsWith("companies/");
-}
-
-/**
- * Test-only export. Kept under a `_testing` namespace so the module's public
- * surface stays focused on `share()` / `ShareOptions` / `ShareResult` while
- * regression-critical regex contracts (the conflict-mirror pattern) can be
- * pinned by direct unit tests without round-tripping through share().
- *
- * Do NOT import from `_testing` outside of tests in this package.
- */
-export const _testing = {
-  isEphemeralPath,
-  EPHEMERAL_PATH_PATTERN,
-  wrapFilterWithIgnoreVisibility,
-  collectFiles,
-  resolveNamedPath,
-  isWithinLexicalOrReal,
-  defaultConsoleLogger,
-};
-
-/**
- * Stage-1 classification for a single local file in a push run. Pre-HEAD —
- * only inputs we can evaluate locally (size limit, journal hash, optional
- * skip-unchanged) determine the action. Files that pass classification as
- * `upload` are still subject to a per-file HEAD + 3-way conflict check in
- * Stage 2 before the actual PUT, so the `filesToUpload` count in the plan
- * event is an upper bound: it includes files that may turn out to be
- * conflicts. V1.5 follow-up: replace per-file HEAD with a single LIST so
- * conflicts can be classified up-front and reported in the plan.
- */
-type PushPlanItem =
-  | {
-      action: "upload";
-      kind: "file";
-      absolutePath: string;
-      relativePath: string;
-      localHash: string;
-      size: number;
-    }
-  | {
-      action: "upload";
-      kind: "symlink";
-      absolutePath: string;
-      relativePath: string;
-      // The link's target string verbatim (whatever readlink returned).
-      // Hashed into localHash so a target rewrite re-uploads even when
-      // skipUnchanged is on; size stays 0 because the wire body is empty.
-      target: string;
-      localHash: string;
-      size: 0;
-    }
-  | {
-      action: "skip-size-limit";
-      absolutePath: string;
-      relativePath: string;
-    }
-  | {
-      action: "skip-unchanged";
-      absolutePath: string;
-      relativePath: string;
-      // Present only when the lstat fast-path MISSED but the re-hash confirmed
-      // the bytes are unchanged (a touched-but-identical file, or a pre-5.36
-      // entry with no mtimeMs). Carries the current (mtimeMs, size) so the
-      // apply loop can refresh the journal entry — otherwise the fast-path
-      // keeps missing and re-hashes the file on every future sync. No content
-      // change: this never uploads or conflicts.
-      restamp?: { mtimeMs: number; size: number };
-    };
-
-interface PushPlan {
-  items: PushPlanItem[];
-  filesToUpload: number;
-  bytesToUpload: number;
-  filesToSkip: number;
-}
-
-/**
- * Pure Stage-1 pass for push: walk the candidate file list, hash each one,
- * apply the size-limit and skip-unchanged gates, and return a classified
- * plan plus aggregate counts. No S3 calls, no journal writes, no event
- * emission.
- *
- * The conflict count is intentionally absent from the returned `PushPlan` —
- * detecting a push conflict requires a remote HEAD that we defer to Stage 2.
- * Consumers that want a conflict count get it from the `complete` event.
- */
-function computePushPlan(
-  filesToShare: CollectedEntry[],
-  journal: SyncJournal,
-  skipUnchanged: boolean,
-): PushPlan {
-  const items: PushPlanItem[] = [];
-
-  for (const entry of filesToShare) {
-    const { absolutePath, relativePath } = entry;
-
-    // Symlinks bypass the size-limit gate (the wire body is small,
-    // bounded by target length) and hash the target through the
-    // symlink-namespaced hash so a symlink to "real.md" can never
-    // collide with a regular file containing the bytes "real.md" in
-    // the skip-unchanged gate. The target is what we're actually
-    // uploading, so its hash is what should drive change detection —
-    // a target rewrite must re-fire an upload even when the link
-    // itself "looks" identical.
-    if (entry.kind === "symlink") {
-      const localHash = hashSymlinkTarget(entry.target);
-
-      if (skipUnchanged) {
-        const existing = journal.files[relativePath];
-        if (existing && existing.hash === localHash) {
-          items.push({ action: "skip-unchanged", absolutePath, relativePath });
-          continue;
-        }
-      }
-
-      items.push({
-        action: "upload",
-        kind: "symlink",
-        absolutePath,
-        relativePath,
-        target: entry.target,
-        localHash,
-        size: 0,
-      });
-      continue;
-    }
-
-    if (!isWithinSizeLimit(absolutePath)) {
-      items.push({ action: "skip-size-limit", absolutePath, relativePath });
-      continue;
-    }
-
-    // Fast-path (5.36.0): before SHA256-ing the file, lstat it and compare
-    // (size, mtimeMs) against the journal entry. When both match, treat the
-    // file as unchanged without reading its bytes. This is the same
-    // industry-standard "is it changed?" cheap-check rsync and gitignore
-    // use. Trade-off: a same-length edit that doesn't bump mtime will be
-    // missed — vanishingly rare in practice. The big win is on no-op syncs
-    // (most syncs): a 5000-file tree of mostly-unchanged content used to
-    // SHA256 every file on every walk. Now it lstats once and short-
-    // circuits in O(file count) instead of O(file bytes).
-    //
-    // Only applies when `skipUnchanged` is on AND the journal carries an
-    // `mtimeMs` for this path AND the path is a regular file (symlinks
-    // already hash via the cheap hashSymlinkTarget path above). Entries
-    // without `mtimeMs` (pre-5.36 journal) fall through to the hash path;
-    // the next upload stamps the field so subsequent syncs use the fast-
-    // path. Back-compat is automatic.
-    if (skipUnchanged) {
-      const existing = journal.files[relativePath];
-      if (existing && existing.mtimeMs !== undefined && existing.hash) {
-        try {
-          const lstat = fs.lstatSync(absolutePath);
-          if (
-            lstat.isFile() &&
-            lstat.size === existing.size &&
-            lstat.mtimeMs === existing.mtimeMs
-          ) {
-            items.push({ action: "skip-unchanged", absolutePath, relativePath });
-            continue;
-          }
-        } catch {
-          // Fall through to hashFile, which will surface the I/O error in
-          // its own readFileSync.
-        }
-      }
-    }
-
-    const localHash = hashFile(absolutePath);
-
-    if (skipUnchanged) {
-      const existing = journal.files[relativePath];
-      if (existing && existing.hash === localHash) {
-        // Reaching here means the fast-path did NOT short-circuit (mtime or
-        // size moved, or the entry predates mtimeMs) yet the re-hash proved the
-        // bytes are unchanged — a no-op skip. Capture the current (mtimeMs,
-        // size) so the apply loop refreshes the journal; without it the
-        // fast-path keeps missing and re-hashes this file on every sync. Only
-        // attach when the stored stat actually differs (avoid a needless
-        // journal write on an already-current entry). Stat failure → no
-        // restamp; the skip still stands.
-        let restamp: { mtimeMs: number; size: number } | undefined;
-        try {
-          const lstat = fs.lstatSync(absolutePath);
-          if (
-            lstat.isFile() &&
-            (existing.mtimeMs !== lstat.mtimeMs || existing.size !== lstat.size)
-          ) {
-            restamp = { mtimeMs: lstat.mtimeMs, size: lstat.size };
-          }
-        } catch {
-          /* best-effort; a stat error just forgoes the fast-path refresh */
-        }
-        items.push({ action: "skip-unchanged", absolutePath, relativePath, restamp });
-        continue;
-      }
-    }
-
-    const size = fs.statSync(absolutePath).size;
-    items.push({
-      action: "upload",
-      kind: "file",
-      absolutePath,
-      relativePath,
-      localHash,
-      size,
-    });
-  }
-
-  let filesToUpload = 0;
-  let bytesToUpload = 0;
-  let filesToSkip = 0;
-  for (const item of items) {
-    if (item.action === "upload") {
-      filesToUpload++;
-      bytesToUpload += item.size;
-    } else {
-      filesToSkip++;
-    }
-  }
-
-  return { items, filesToUpload, bytesToUpload, filesToSkip };
-}
-
-export interface ShareOptions {
-  /** Path(s) to share (files or directories) */
-  paths: string[];
-  /** Company slug or UID (defaults to active company from config) */
-  company?: string;
-  /** Optional message attached to journal entries */
-  message?: string;
-  /** Non-interactive conflict strategy */
-  onConflict?: ConflictStrategy;
-  /**
-   * Vault service config — used when share() must resolve the entity and vend
-   * STS credentials itself (the default CLI path).
-   *
-   * Mutually exclusive with `entityContext`. Exactly one of the two must be
-   * provided; supplying both throws.
-   */
-  vaultConfig?: VaultServiceConfig;
-  /**
-   * Pre-resolved entity context. When provided, share() skips its own
-   * `resolveEntityContext` call (no entity lookup, no STS vending) and uses
-   * these credentials directly.
-   *
-   * Use case: AppBar HQ Sync vends task-scoped creds via `/sts/vend-child`
-   * (preserving audit traceability via `task_id` + `task_description`)
-   * before invoking `hq sync push` as a subprocess. The subprocess reads the
-   * EntityContext JSON from stdin and passes it here.
-   *
-   * IMPORTANT: When using `entityContext`, the caller is responsible for
-   * vending credentials with enough TTL to cover the entire upload run.
-   * share() cannot auto-refresh a pre-vended context (it has no Cognito
-   * token to re-vend with) — if the credentials are expiring mid-run,
-   * share() throws a clear error rather than silently failing on the
-   * next S3 call.
-   *
-   * Mutually exclusive with `vaultConfig`.
-   */
-  entityContext?: EntityContext;
-  /** HQ root directory */
-  hqRoot: string;
-  /**
-   * Per-file event callback. When present, suppresses the default
-   * `console.log`/`console.error` human output — same contract as `sync()`.
-   * This is the seam `hq-sync-runner` uses to stream ndjson for push events.
-   */
-  onEvent?: (event: SyncProgressEvent) => void;
-  /**
-   * When true, files whose local hash matches the journal entry from the
-   * last sync are skipped (no remote HEAD, no upload). This is the gate
-   * that makes "push everything that changed" efficient — without it, a
-   * bidirectional Sync Now would re-upload every file each tick.
-   *
-   * Default false to preserve `hq share <file>` semantics: when a user
-   * explicitly names a file, they expect it to be sent even if the local
-   * hash matches the last-sync state (e.g. to re-heal a bucket).
-   */
-  skipUnchanged?: boolean;
-  /**
-   * When true, journal entries whose local file is gone trigger a remote
-   * `DeleteObject`. Only entries whose key falls under one of the supplied
-   * `paths` (after resolution to absolute paths under `companies/{slug}/`)
-   * are considered, so `hq share <file>` can never sweep deletes outside
-   * the named scope.
-   *
-   * Vault buckets have versioning enabled, so the delete is soft: a
-   * delete-marker becomes the current version and prior object versions
-   * remain recoverable indefinitely. The pull-side `listRemoteFiles` skips
-   * objects whose current version is a delete-marker (default
-   * `ListObjectsV2` behavior), so a deletion stops the next pull from
-   * re-downloading the file on this and any other machine.
-   *
-   * Default false to preserve `hq share <file>` semantics — only the
-   * full-tree bidirectional runner opts in.
-   */
-  propagateDeletes?: boolean;
-  /**
-   * Policy for which journal entries `propagateDeletes` is willing to
-   * convert into remote `DeleteObject` calls. Only consulted when
-   * `propagateDeletes === true`.
-   *
-   *   - `"currency-gated"` (safest; default scheduled for 5.25 after soak):
-   *     for each candidate, issue a remote HEAD and compare the current
-   *     remote ETag against the journal's
-   *     last-recorded `remoteEtag`. Match → safe-to-delete (this machine is
-   *     current for the file, so the local deletion reflects an intentional
-   *     removal AFTER seeing the latest remote version). Mismatch → refuse
-   *     and emit `delete-refused-stale-etag`; the journal entry is left
-   *     intact so the next pull leg re-pulls via the same hasRemoteChanged
-   *     path. 404 → tombstone: drop the journal entry, no DeleteObject (the
-   *     remote was already gone). Strictly safer than `owned-only` because
-   *     it gates on per-file proof of currency rather than direction-of-
-   *     origin — files that arrived via `/update-hq` (direction:"down") can
-   *     legitimately be deleted by the device that pulled them, as long as
-   *     no other device has touched them since.
-   *   - `"owned-only"` (current default in 5.24): only entries whose journal
-   *     `direction === "up"` are eligible. That is, only files this machine
-   *     previously uploaded can be remotely deleted on its behalf. Entries
-   *     recorded as pulled from elsewhere are never delete-propagated.
-   *     Default in 5.24 while currency-gated soaks; scheduled to lose the
-   *     default in 5.25. Downside: any file that arrived via `/update-hq`
-   *     or another device's push is stuck on remote forever once locally
-   *     removed, because no device "owns" it under this rule.
-   *   - `"all"`: legacy behaviour — every in-scope journal entry whose
-   *     local file is missing is eligible (regardless of direction or
-   *     currency). The bidirectional runner's first-push and any tool that
-   *     wants to mirror a destructive local checkout opts in here
-   *     explicitly. Use with care — a stale device can erase peer uploads.
-   *
-   * Independently of this policy, an entry is also dropped from the plan
-   * when (a) it matches `EPHEMERAL_PATH_PATTERN` (conflict mirrors never
-   * propagate), or (b) neither the file-shape nor the directory-shape probe
-   * of `shouldSync` accepts the path — i.e. the current ignore filter would
-   * have skipped the path on pull. That symmetry blocks the failure mode
-   * where a path was filtered locally but lived in the vault (and the
-   * journal) from an older HQ layout or a different machine, causing the
-   * next push to erase it.
-   */
-  propagateDeletePolicy?: "currency-gated" | "owned-only" | "all";
-  /**
-   * Explicit vault-relative delete roots captured by a live watcher before a
-   * scoped push. These roots do not need to exist locally; delete execution
-   * still requires a current version-bound intent (or server tombstone).
-   */
-  deleteScopeRoots?: string[];
-  /**
-   * Hq-root-relative key prefixes whose journal entries should be
-   * unconditionally decommissioned from the remote bucket and journal,
-   * independent of whether the local file is present. Each prefix matches
-   * its exact-key form (e.g. "companies/foo") AND any descendant key
-   * (e.g. "companies/foo/knowledge/notes.md") — same prefix semantics as
-   * `propagateDeletes`'s scope roots.
-   *
-   * Use case: a company that previously synced to the operator's personal
-   * bucket has been promoted to its own team bucket (`/designate-team`).
-   * Its keys at `companies/{slug}/...` in the personal bucket are now
-   * orphans — the on-disk files still exist (the team bucket is the new
-   * canonical home), so the standard `propagateDeletes` gate ("local file
-   * missing") never fires. This option asserts "these objects no longer
-   * belong in THIS bucket regardless of local state" and uses the same
-   * DeleteObject + journal-removal path as `propagateDeletes`.
-   *
-   * Honors `propagateDeletePolicy`. Under `"owned-only"` (this function's
-   * own fallback when the caller passes nothing; every live caller passes
-   * `resolveDeletePolicy()`, which defaults to `"currency-gated"`) only
-   * journal entries with `direction === "up"` are decommissioned, so a
-   * misconfigured caller never erases content pulled from elsewhere.
-   *
-   * Independent of `propagateDeletes`: callers can opt into decommission
-   * without enabling general delete propagation. In practice the runner
-   * sets both for the personal slot.
-   */
-  decommissionPrefixes?: string[];
-  /**
-   * Identity stamped onto each uploaded object's S3 user metadata
-   * (`created-by`, `created-by-sub`, `created-at`). The hq-console vault UI
-   * reads `Metadata['created-by']` for its "CREATED BY" column; uploads
-   * without an author leave that column blank for every file synced via
-   * this engine. The runner pipes Cognito idToken claims through here.
-   */
-  author?: UploadAuthor;
-  /**
-   * When true, share() targets the caller's person-entity bucket: syncRoot
-   * is `hqRoot` itself (NOT `hqRoot/companies/<slug>/`), so remote keys are
-   * hq-root-relative (e.g. ".claude/skills/foo.md", "knowledge/notes.md") to
-   * match the Rust hq-sync first-push contract in
-   * `src-tauri/src/commands/personal.rs`. The exclusion of top-level dirs
-   * (.git, companies, core, data, personal, repos, workspace) is enforced
-   * by the runner — share() trusts its `paths` input.
-   */
-  personalMode?: boolean;
-  /**
-   * Override for the per-slug journal file name. Defaults to `ctx.slug`. The
-   * runner passes `journalSlug: "personal"` for the personal slot so the TS
-   * push and the Rust personal first-push share idempotency state under one
-   * `sync-journal.personal.json` file.
-   */
-  journalSlug?: string;
-  /**
-   * Effective ACL push scope as a list of company-relative prefixes (the same
-   * coalesced `prefixSet` the pull leg uses for `syncMode: "shared"`). When
-   * provided, the upload + delete plans are filtered to paths covered by these
-   * prefixes — any candidate outside them is skipped (and surfaced via a
-   * `scope-excluded` event) rather than PUT, because the vended child
-   * credential is scoped to exactly these prefixes and an out-of-scope PUT
-   * draws the server's correct 403 `SCOPE_EXCEEDS_PARENT`.
-   *
-   * `undefined` (the owner/`all` case, and `hq share <file>`) applies NO scope
-   * filter — full access. An empty array means "no granted prefixes" → every
-   * path is out of scope (mirrors the pull side's `isCoveredByAny([])`).
-   */
-  prefixSet?: ScopePrefixInput[];
-  /**
-   * Pre-fetched FILE_TOMBSTONE map (POSIX key → tombstone) for the push-side
-   * delete-resync consult. When omitted, share() fetches it itself via
-   * `fetchCompanyTombstones` for COMPANY vaults that have a `vaultConfig`
-   * (personal vaults and pre-vended `entityContext`-only callers without a
-   * `vaultConfig` degrade to no-suppression — the safe, legacy direction).
-   *
-   * Injection is an optimization + test seam: a sync run that already fetched
-   * tombstones for the pull leg can hand the same map to the push leg to avoid a
-   * second round-trip, and tests can supply a controlled map without stubbing
-   * the network. See the consult in the Stage-2 classification pass.
-   */
-  fileTombstones?: Map<string, CompanyTombstone>;
-  /**
-   * What to do when a path the caller EXPLICITLY named cannot be shipped —
-   * it does not resolve under any base, or it resolves outside the company
-   * folder (see `ShareResult.unreachablePaths`).
-   *
-   * - `"error"` (DEFAULT): a path that EXISTS on disk but resolves outside the
-   *   company folder throws {@link UnreachablePushPathsError} BEFORE any upload
-   *   runs, so the push is an atomic no-op and the CLI exits nonzero. This is
-   *   ask #2 of feedback_a51cb63d — "error, not warn-skip, when the named file
-   *   exists locally but is unreachable by the resolver". A user who typed a
-   *   path and got "✓ Pushed 0 file(s)" had no way to know their content never
-   *   left the machine. A path that resolves to NOTHING under any base is still
-   *   only warn-recorded (see `collectFatalUnreachablePaths` for why bulk
-   *   membership fanout depends on that).
-   * - `"warn"`: record it on the result + emit the `not-shipped` event and
-   *   carry on, never throwing. For callers whose `paths` are INTERNAL walk
-   *   roots rather than user input — the background sync runner — where a path
-   *   disappearing mid-run is a benign race (a directory removed between the
-   *   scan and the push) and must never fail an unattended sync.
-   */
-  unreachablePathPolicy?: "error" | "warn";
-}
-
-/** Why an explicitly-named push path could not be shipped. */
-export type UnreachablePathReason = "missing" | "outside-company" | "unreadable-link";
-
-/**
- * Thrown by `share()` when a caller-named path cannot be pushed and
- * `unreachablePathPolicy` is `"error"` (the default). Raised while the plans
- * are still being built, so NOTHING has been uploaded, journaled, or deleted
- * when it surfaces — the failed push leaves no partial state behind.
- */
-export class UnreachablePushPathsError extends Error {
-  /** Caller's original spellings, verbatim (see the CollectHooks contract). */
-  readonly paths: string[];
-  /** Per-path reason, keyed by the same original spelling. */
-  readonly reasons: Record<string, UnreachablePathReason>;
-
-  constructor(unreachable: ReadonlyMap<string, UnreachablePathReason>, syncRoot: string) {
-    const paths = [...unreachable.keys()];
-    const lines = paths.map((p) => {
-      const reason = unreachable.get(p);
-      if (reason === "outside-company") {
-        return `  · ${p} — resolves outside the company folder (${syncRoot})`;
-      }
-      if (reason === "unreadable-link") {
-        return `  · ${p} — symbolic link target could not be read; it was not dereferenced or uploaded`;
-      }
-      return `  · ${p} — not found under the hq root, the company folder, or the current directory`;
-    });
-    super(
-      `${paths.length} named path${paths.length === 1 ? "" : "s"} could not be pushed; ` +
-        `nothing was uploaded.\n${lines.join("\n")}\n` +
-        `A path reached through a symlink is only pushable when it stays inside the HQ tree ` +
-        `(e.g. companies/<slug>/knowledge → repos/private/knowledge-<slug>); one that points ` +
-        `outside HQ has to sync through whatever owns it, not the vault.`,
-    );
-    this.name = "UnreachablePushPathsError";
-    this.paths = paths;
-    this.reasons = Object.fromEntries(unreachable);
-  }
-}
-
-export interface ShareResult {
-  filesUploaded: number;
-  bytesUploaded: number;
-  filesSkipped: number;
-  /**
-   * Number of remote `DeleteObject` calls that succeeded this run. Always 0
-   * when `propagateDeletes` is false. The corresponding journal entries are
-   * removed in the same pass so the next sync sees the key as truly gone.
-   * Does NOT include tombstones (remote was already 404; no DELETE was
-   * issued — see `filesTombstoned`) or refused-stale entries (currency-
-   * gated refused because remote etag drifted — see `filesRefusedStale`).
-   */
-  filesDeleted: number;
-  /**
-   * Number of journal entries dropped because the remote was already 404 at
-   * HEAD time (cleaned out-of-band — e.g. someone hand-deleted via the S3
-   * console, or another tool ran a destructive operation). No `DeleteObject`
-   * was issued for these; the journal converges with reality. Always 0 when
-   * `propagateDeletes` is false or `propagateDeletePolicy !== "currency-gated"`.
-   */
-  filesTombstoned: number;
-  /**
-   * Number of delete candidates refused by the `currency-gated` policy
-   * because the remote object's current ETag no longer matches the journal's
-   * recorded one (some other device modified the file since this device last
-   * synced it) — OR because the journal entry is a legacy record with no
-   * `remoteEtag` to compare against. Neither S3 nor the journal is mutated
-   * for these; the next pull leg re-pulls naturally via `hasRemoteChanged`.
-   * Always 0 when `propagateDeletes` is false or policy is not
-   * `currency-gated`.
-   */
-  filesRefusedStale: number;
-  /**
-   * Paths corresponding to `filesRefusedStale`, capped at 50 to keep the
-   * event payload bounded (mirrors `newFiles` capping). Surfaces *which*
-   * paths were refused so operators can triage the recurring
-   * \`filesRefusedStale: 205\` signal flagged in the 5.33.0 deep-test —
-   * the count alone is impossible to investigate because the per-file
-   * \`delete-refused-stale-etag\` events vanish from the event stream
-   * once the runner has folded them into the totals.
-   */
-  filesRefusedStalePaths: string[];
-  /**
-   * Number of uploads suppressed by the push-side FILE_TOMBSTONE consult — keys
-   * an authoritative delete (`hq files delete`) tombstoned that this machine
-   * still held as the unchanged synced baseline. Skipping the upload is what
-   * stops a behind peer from resurrecting an authoritatively-deleted key. Always
-   * 0 when there are no tombstones for in-scope keys (the common case) or when
-   * the run can't load tombstones (personal vault / no `vaultConfig`).
-   */
-  filesSuppressedByTombstone: number;
-  /**
-   * Number of paths blocked by `PERSONAL_VAULT_DEFAULT_EXCLUSIONS` during this
-   * run (push leg, personalMode=true). Includes both files that would have
-   * uploaded and journal entries that would have been included in the delete
-   * plan; deduplicated across walks. Always 0 outside personalMode. Mirrors
-   * the `count` field of the `personal-vault-out-of-policy` event (which is
-   * emitted exactly once if this is > 0).
-   */
-  filesExcludedByPolicy: number;
-  /**
-   * Number of distinct company-relative paths/prefixes skipped because they
-   * fell OUTSIDE the run's ACL `prefixSet` (member/guest scoped push). Always
-   * 0 when `prefixSet` is undefined (owner/`all`) or the whole tree is in
-   * scope. Mirrors the `count` field of the `scope-excluded` event (emitted
-   * once if this is > 0). These paths were never PUT, so the server's correct
-   * 403 `SCOPE_EXCEEDS_PARENT` is never triggered and the company still syncs
-   * its in-scope subset.
-   */
-  filesExcludedByScope: number;
-  /**
-   * Number of distinct hq-root-relative paths skipped by the base ignore
-   * filter that look like real content rather than expected build/VCS/cache
-   * noise. Mirrors the `count` field of the `ignore-excluded` event (emitted
-   * once if this is > 0).
-   */
-  filesExcludedByIgnore: number;
-  /**
-   * Paths the caller EXPLICITLY named for push that exist locally but the
-   * resolver could not place under the company folder (or could not find under
-   * any base). Empty in the common case (internal walk roots are always the
-   * reachable company folder). A non-empty list means the push did NOT ship
-   * something the caller asked for.
-   *
-   * Only ever non-empty under `unreachablePathPolicy: "warn"` — the DEFAULT
-   * `"error"` policy throws {@link UnreachablePushPathsError} instead of
-   * returning, so an interactive `hq sync push` fails loudly rather than
-   * reporting the pre-fix silent "Pushed 0 file(s)" success. This field is the
-   * warn-mode surface for unattended callers (sync runner / watcher).
-   *
-   * Entries are the caller's ORIGINAL spellings, verbatim — a relative token
-   * stays relative, an absolute token stays absolute — so the list is directly
-   * comparable to the `paths` input. See the CollectHooks spelling contract.
-   * Mirrors the `not-shipped` event with `reason: "unreachable-path"`.
-   */
-  unreachablePaths: string[];
-  /**
-   * Company-relative keys of directory symlinks that were recorded as links but
-   * NOT descended because their target lives outside the company folder — their
-   * contents sync via their own repo, not the vault. Surfaced so files created
-   * under such a link (e.g. `companies/{co}/knowledge` → a linked repo) no
-   * longer vanish from every push bucket without a trace. Mirrors the
-   * `not-shipped` event with `reason: "linked-subtree"`.
-   */
-  linkedSubtreesNotShipped: string[];
-  /**
-   * Paths (company-relative) that were detected as push conflicts. Mirrors
-   * `SyncResult.conflictPaths` so push and pull surface conflicts the same
-   * way to runner/UI consumers.
-   */
-  conflictPaths: string[];
-  /** Uncapped per-path delete outcomes used by scoped watcher publication. */
-  pathResults?: SharePathResult[];
-  aborted: boolean;
-}
-
-export type ShareDeleteRefusalReason =
-  | "stale-etag"
-  | "legacy-no-etag"
-  | "bulk-asymmetry"
-  | "divergent-local"
-  | "missing-delete-intent"
-  | "intent-changed"
-  | "recreated-locally"
-  | "transfer-error";
-
-export interface SharePathResult {
-  path: string;
-  status: "accepted" | "refused";
-  operation: "delete" | "tombstone";
-  reason?: ShareDeleteRefusalReason;
-}
-
-/**
- * A conditional-write fence rejection — the SDK's 412 (`name:
- * "PreconditionFailed"`) or the presigned transport's mirror of it. Means
- * the remote moved past the etag this pass inspected (If-Match) or an
- * object appeared at a key we believed absent (If-None-Match). Always a
- * conflict, never a transport failure.
- */
-function isPreconditionFailed(err: unknown): boolean {
-  if (err && typeof err === "object" && "name" in err) {
-    return (err as { name?: unknown }).name === "PreconditionFailed";
-  }
-  return false;
-}
-
-/**
- * Wrap an existing path filter (ignore filter, optionally already wrapped with
- * the personal-vault defaults) so that paths OUTSIDE the run's ACL `prefixSet`
- * are rejected before they enter the upload OR delete plan. Keeps the
- * `(absolutePath, isDir) => boolean` shape the rest of share() already uses
- * (collectFiles / walkDir / computeDeletePlan), so wiring is one line at the
- * filter-construction site — exactly like `wrapFilterWithPersonalVaultDefaults`.
- *
- * Files use `isCoveredByAny` (plain `startsWith`); directories use
- * `isDirInScope` (descend if the dir is inside a grant OR a grant is inside
- * the dir) so the walk still reaches deep/exact-file grants. Rejected entries
- * are tagged via `onScopeExcluded` (directories with a trailing slash) so the
- * runner can emit a single `scope-excluded` summary naming what was skipped.
- */
-function wrapFilterWithScope(
-  underlying: (absPath: string, isDir?: boolean) => boolean,
-  syncRoot: string,
-  prefixSet: readonly ScopePrefixInput[],
-  onScopeExcluded: (rel: string) => void,
-): (absPath: string, isDir?: boolean) => boolean {
-  return (absPath: string, isDir?: boolean) => {
-    if (!underlying(absPath, isDir)) return false;
-    const rel = vaultKeyForLocalPath(syncRoot, absPath);
-    if (rel === "" || rel.startsWith("..")) return true; // root / outside — defer
-    if (isDir) {
-      if (isDirInScope(rel, prefixSet)) return true;
-      onScopeExcluded(rel.endsWith("/") ? rel : rel + "/");
-      return false;
-    }
-    if (isCoveredByAny(rel, prefixSet)) return true;
-    onScopeExcluded(rel);
-    return false;
-  };
-}
-
-/**
- * Wrap the base ignore filter so push can observe paths it rejects before
- * personal-vault policy or ACL scope wrappers add their own exclusions.
- * Every base-ignore rejection increments `onAnyExcluded`; only rejections
- * that do NOT match expected build/VCS/cache noise are tagged through
- * `onIgnoreExcluded` for the one-shot `ignore-excluded` summary.
- */
-export function wrapFilterWithIgnoreVisibility(
-  underlying: (absPath: string, isDir?: boolean) => boolean,
-  hqRoot: string,
-  onIgnoreExcluded: (relPath: string) => void,
-  onAnyExcluded?: () => void,
-): (absPath: string, isDir?: boolean) => boolean {
-  return (absPath: string, isDir?: boolean) => {
-    const allowed = underlying(absPath, isDir);
-    if (allowed) return true;
-
-    onAnyExcluded?.();
-    const rel = vaultKeyForLocalPath(hqRoot, absPath);
-    if (rel === "" || rel.startsWith("..")) return false;
-    if (!isExpectedIgnore(rel)) onIgnoreExcluded(rel);
-    return false;
-  };
-}
-
-/**
- * Share local file(s) to the entity vault.
- */
-export async function share(options: ShareOptions): Promise<ShareResult> {
-  const run = await createPushRunContext(options);
-  const counters = createShareCounters();
-  const filesRefusedStalePaths: string[] = [];
-  const conflictPaths: string[] = [];
-  const pathResults: SharePathResult[] = [];
-
-  const plans = await buildSharePlans(run);
-  const uploadResult = await executeUploads(
-    run,
-    plans.pushPlan,
-    counters,
-    conflictPaths,
-  );
-  if (uploadResult.aborted) {
-    return buildShareResult(
-      run,
-      counters,
-      filesRefusedStalePaths,
-      uploadResult.abortFlightConflictPaths,
-      pathResults,
-      true,
-    );
-  }
-
-  await executeDeletes(
-    run,
-    plans.deletePlan,
-    plans.decommissionPlan,
-    counters,
-    filesRefusedStalePaths,
-    pathResults,
-  );
-  finalizeShareJournal(run);
-  throwUploadWorkerErrors(uploadResult.workerErrors);
-
-  return buildShareResult(
-    run,
-    counters,
-    filesRefusedStalePaths,
-    conflictPaths,
-    pathResults,
-    false,
-  );
-}
-
-type DeletePolicy = NonNullable<ShareOptions["propagateDeletePolicy"]>;
-type ShareEmit = (event: SyncProgressEvent) => void;
-type UploadPlanItem = Extract<PushPlanItem, { action: "upload" }>;
-type JournalFileEntry = SyncJournal["files"][string];
-
-interface PushRunContext {
-  options: ShareOptions;
-  paths: string[];
-  message?: string;
-  onConflict?: ConflictStrategy;
-  vaultConfig?: VaultServiceConfig;
-  entityContext?: EntityContext;
-  hqRoot: string;
-  skipUnchanged?: boolean;
-  propagateDeletes?: boolean;
-  propagateDeletePolicy: DeletePolicy;
-  emit: ShareEmit;
-  companyRef: string;
-  ctx: EntityContext;
-  syncRoot: string;
-  shouldSync: (filePath: string, isDir?: boolean) => boolean;
-  journalSlug: string;
-  journal: SyncJournal;
-  excludedSet: Set<string>;
-  excludedById: Record<string, number>;
-  scopeExcludedSet: Set<string>;
-  ignoreExcludedSet: Set<string>;
-  ignoreExcludedTotal: { value: number };
-  /** Explicitly-named push paths that exist locally but the resolver could not
-   * place under the company folder (or find at all), keyed by the CALLER'S
-   * ORIGINAL spelling (see the CollectHooks spelling contract) and valued by
-   * why it could not be shipped. Non-empty ⇒ the push did NOT ship something
-   * the caller named — surfaced so a "Pushed 0 file(s)" is never a silent
-   * false success, and (under the default `unreachablePathPolicy: "error"`)
-   * raised as a hard failure before any upload runs. */
-  unreachablePaths: Map<string, UnreachablePathReason>;
-  /** Company-relative keys of directory symlinks recorded but not descended
-   * because their target lives outside the company folder (contents sync via
-   * their own repo, not the vault). */
-  linkedSubtreeSet: Set<string>;
-}
-
-interface ShareCounters {
-  filesUploaded: number;
-  bytesUploaded: number;
-  filesSkipped: number;
-  filesDeleted: number;
-  filesTombstoned: number;
-  filesRefusedStale: number;
-  filesSuppressedByTombstone: number;
-}
-
-interface SharePlans {
-  pushPlan: PushPlan;
-  deletePlan: DeletePlan;
-  decommissionPlan: string[];
-}
-
-interface UploadExecutionResult {
-  aborted: boolean;
-  abortFlightConflictPaths: string[];
-  workerErrors: Error[];
-}
-
-const REFUSED_STALE_PATH_CAP = 50;
-
-async function createPushRunContext(options: ShareOptions): Promise<PushRunContext> {
-  const { paths, company, message, onConflict, vaultConfig, entityContext, hqRoot, skipUnchanged, propagateDeletes } = options;
-  const propagateDeletePolicy: DeletePolicy =
-    options.propagateDeletePolicy ?? "owned-only";
-  const baseEmit = options.onEvent ?? defaultConsoleLogger;
-
-  if (vaultConfig && entityContext) {
-    throw new Error(
-      "share() requires exactly one of `vaultConfig` or `entityContext`, not both. " +
-      "Pass `vaultConfig` to vend credentials internally, or `entityContext` to use pre-vended ones.",
-    );
-  }
-  if (!vaultConfig && !entityContext) {
-    throw new Error(
-      "share() requires either `vaultConfig` (for internal STS vending) " +
-      "or `entityContext` (pre-vended credentials).",
-    );
-  }
-
-  const companyRef =
-    company ?? entityContext?.slug ?? 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: EntityContext = entityContext
-    ? entityContext
-    : await resolveEntityContext(companyRef, vaultConfig!);
-
-  // NOTE (removed 6.14.48): a `prs_`-scoped coercion used to silently rewrite
-  // `owned-only` -> `currency-gated` here (366721b). It was correct for the
-  // problem it was written against and is now actively harmful, for three
-  // reasons that only became true later:
-  //
-  //   1. Its ONLY reachable effect in production was to override an EXPLICIT
-  //      `owned-only`. Every live caller passes a policy
-  //      (`sync-runner-company.ts` -> `resolveDeletePolicy()`), and that
-  //      resolver already defaults to `currency-gated`. So the coercion never
-  //      fired on a default run — it fired exactly when an operator had set
-  //      `HQ_SYNC_DELETE_POLICY=owned-only`, i.e. the documented rollback.
-  //   2. Once delete authorization moved to ETag currency (no watcher-minted
-  //      intent required), that override stopped being cosmetic: an operator
-  //      reaching for the rollback because deletes were misbehaving would keep
-  //      getting intent-less etag-only deletes on their personal vault. A
-  //      rollback knob that silently exempts a vault is not a rollback knob.
-  //   3. Its motivating bug — the May-27 `personal/.obsidian/*.drift-*` leak —
-  //      is fixed twice over by mechanisms that postdate it: the vault-litter
-  //      drain (6.0.2) drains `.drift-*` markers ahead of every policy gate,
-  //      and etag-gated deletes propagate an intent-less `direction:"down"`
-  //      removal under the default policy without needing any coercion.
-  //
-  // So `owned-only` now means owned-only on every vault kind. It is the strict
-  // rollback path and must stay strictly stricter than the default everywhere.
-
-  // Mirror push progress into the shared cross-process snapshot (see sync.ts).
-  // Record the friendly company slug, or null for the personal vault so the
-  // menubar shows "Personal" — never the raw prs_/cmp_ UID.
-  const recordProgress = createSyncProgressRecorder({
-    company:
-      ctx.uid.startsWith("prs_") || options.personalMode === true
-        ? null
-        : ctx.slug,
-    phase: "push",
-  });
-  const emit: ShareEmit = (event) => {
-    baseEmit(event);
-    recordProgress(event);
-  };
-
-  const syncRoot = options.personalMode === true
-    ? hqRoot
-    : path.join(hqRoot, "companies", ctx.slug);
-
-  const ignoreFilter = createIgnoreFilter(hqRoot);
-  const ignoreExcludedSet = new Set<string>();
-  const ignoreExcludedTotal = { value: 0 };
-  const recordedIgnoreFilter = wrapFilterWithIgnoreVisibility(
-    ignoreFilter,
-    hqRoot,
-    (rel) => {
-      ignoreExcludedSet.add(rel);
-    },
-    () => {
-      ignoreExcludedTotal.value++;
-    },
-  );
-  const excludedSet = new Set<string>();
-  const excludedById: Record<string, number> = {};
-  const onExcluded = (rel: string, match: PersonalVaultExclusion) => {
-    if (excludedSet.has(rel)) return;
-    excludedSet.add(rel);
-    excludedById[match.id] = (excludedById[match.id] ?? 0) + 1;
-  };
-  const scopeExcludedSet = new Set<string>();
-  const onScopeExcluded = (rel: string) => {
-    scopeExcludedSet.add(rel);
-  };
-  const unreachablePaths = new Map<string, UnreachablePathReason>();
-  const linkedSubtreeSet = new Set<string>();
-  const baseFilter = options.personalMode === true
-    ? wrapFilterWithPersonalVaultDefaults(recordedIgnoreFilter, syncRoot, onExcluded)
-    : recordedIgnoreFilter;
-  const shouldSync = options.prefixSet !== undefined
-    ? wrapFilterWithScope(baseFilter, syncRoot, options.prefixSet, onScopeExcluded)
-    : baseFilter;
-  const journalSlug = options.journalSlug ?? ctx.slug;
-  if (journalSlug === PERSONAL_VAULT_JOURNAL_SLUG) migratePersonalVaultJournal();
-  const journal = readJournal(journalSlug);
-
-  return {
-    options,
-    paths,
-    message,
-    onConflict,
-    vaultConfig,
-    entityContext,
-    hqRoot,
-    skipUnchanged,
-    propagateDeletes,
-    propagateDeletePolicy,
-    emit,
-    companyRef,
-    ctx,
-    syncRoot,
-    shouldSync,
-    journalSlug,
-    journal,
-    excludedSet,
-    excludedById,
-    scopeExcludedSet,
-    ignoreExcludedSet,
-    ignoreExcludedTotal,
-    unreachablePaths,
-    linkedSubtreeSet,
-  };
-}
-
-function createShareCounters(): ShareCounters {
-  return {
-    filesUploaded: 0,
-    bytesUploaded: 0,
-    filesSkipped: 0,
-    filesDeleted: 0,
-    filesTombstoned: 0,
-    filesRefusedStale: 0,
-    filesSuppressedByTombstone: 0,
-  };
-}
-
-async function buildSharePlans(run: PushRunContext): Promise<SharePlans> {
-  const collected = collectFiles(
-    run.paths,
-    run.hqRoot,
-    run.syncRoot,
-    run.shouldSync,
-    {
-      onUnreachablePath: (namedPath, reason) => {
-        // First reason wins: a path is named once, and re-adding would only
-        // churn the map ordering the error message and event sample rely on.
-        if (!run.unreachablePaths.has(namedPath)) {
-          run.unreachablePaths.set(namedPath, reason);
-        }
-      },
-      onLinkedSubtree: (rel) => run.linkedSubtreeSet.add(rel),
-    },
-  );
-  // Ask #2 of feedback_a51cb63d: "error, not warn-skip, when the named file
-  // exists locally but is unreachable by the resolver". This is the throw that
-  // makes it true end-to-end — the CLI's push handler already turns a thrown
-  // error into "✗ Push failed: <message>" + exit 1, so the pre-fix silent
-  // "✓ Pushed 0 file(s)" success can no longer happen for a file that is
-  // sitting right there on disk. It fires HERE, before executeUploads, so a
-  // failed push is also an ATOMIC no-op: nothing uploaded, no journal entry
-  // written, no delete propagated.
-  const fatal = collectFatalUnreachablePaths(run);
-  if (fatal.size > 0) {
-    emitUnreachablePathEvent(run);
-    throw new UnreachablePushPathsError(fatal, run.syncRoot);
-  }
-  // Control-character key filter (macOS Finder Icon\r incident). A key
-  // containing a control character can never be stored — validateVaultUploadKey
-  // rejects it with INVALID_KEY_CONTROL_CHARS — so planning an upload for one
-  // only buys a guaranteed throw inside executeUploads, which lands in the
-  // generic catch and emits `type: "error"`. That is the failure this filter
-  // exists to stop: a non-empty errors[] makes the runner return
-  // PARTIAL_SYNC_EXIT, so ONE such file on disk marks EVERY sync pass failed
-  // forever. A macOS tree seeded with Finder `Icon\r` files produced 100+ per
-  // run, wedging sync indefinitely.
-  //
-  // Structurally identical to the size-limit skip in executeUploads: a
-  // permanently-invalid path is a benign skip, never an error. Symmetric with
-  // the pull leg, which has classified such keys since the 2026-07-11 incident
-  // (see computePullPlan's classifyVaultKey call). Applied before the mode
-  // branch below so it covers personal and company vaults alike.
-  //
-  // Finder icon files are normally already gone by here — createIgnoreFilter
-  // drops them during the walk. This stays as the general guard for any other
-  // control-char path, and as defense for callers that bypass the walker.
-  const controlCharFiltered = collected.filter((entry) => {
-    if (!hasControlCharacters(entry.relativePath)) return true;
-    run.emit({
-      type: "skip-invalid-scoped-key",
-      path: entry.relativePath,
-      errorCode: "INVALID_KEY_CONTROL_CHARS",
-    });
-    return false;
-  });
-
-  // Scope-invalid key filter (incident 2026-07-11). In company mode the sync
-  // root IS the company folder, so a local entry whose vault key starts with
-  // `companies/` can only come from a stale doubled local tree
-  // (companies/{slug}/companies/{slug}/…). Uploading it poisons the bucket
-  // with keys the server validator rejects (INVALID_KEY_COMPANIES_SCOPED) —
-  // the direct-S3 STS transport bypasses server validation. Refuse them here
-  // with a per-key warning; uploadFile/uploadSymlink's validateVaultUploadKey
-  // is the belt-and-suspenders backstop. The pull leg's journal-tombstone
-  // path then CLEANS the doubled tree (local delete + journal drop) instead
-  // of this leg ever re-uploading it. Personal vaults legitimately carry
-  // `companies/{slug}/…` keys, so this only applies in company mode.
-  const filesToShare =
-    run.options.personalMode === true
-      ? controlCharFiltered.filter((entry) => {
-          // `core/<type>` symlinks are generated projections of canonical
-          // personal/package content. Reindex or package wiring owns their
-          // lifecycle, so uploading them creates remote objects that a later
-          // pull can only materialize temporarily before reindex removes them.
-          // Keep ordinary core files eligible: only a symlink is derived.
-          const generatedCoreMirror =
-            entry.kind === "symlink" && isGeneratedCoreMirrorKey(entry.relativePath)
-          if (!generatedCoreMirror) return true;
-
-          // This is a type-aware companion to the path-only personal-vault
-          // default filters. `collectFiles` is the first seam that knows the
-          // entry is a symlink, so record it here for the same summary/result
-          // accounting used by the static exclusions.
-          if (!run.excludedSet.has(entry.relativePath)) {
-            run.excludedSet.add(entry.relativePath);
-            run.excludedById["generated-core-mirror"] =
-              (run.excludedById["generated-core-mirror"] ?? 0) + 1;
-          }
-          return false;
-        })
-      : controlCharFiltered.filter((entry) => {
-          if (!entry.relativePath.startsWith("companies/")) return true;
-          run.emit({
-            type: "skip-invalid-scoped-key",
-            path: entry.relativePath,
-          });
-          return false;
-        });
-  const pushPlan = computePushPlan(
-    filesToShare,
-    run.journal,
-    run.skipUnchanged === true,
-  );
-  const deleteScopeRoots = run.propagateDeletes === true
-    ? resolveDeleteScopeRoots(
-        run.paths,
-        run.hqRoot,
-        run.syncRoot,
-        run.options.deleteScopeRoots,
-      )
-    : [];
-  const deletePlan: DeletePlan = run.propagateDeletes === true
-    ? await computeDeletePlan(
-        run.journal,
-        run.syncRoot,
-        deleteScopeRoots,
-        run.shouldSync,
-        run.propagateDeletePolicy,
-        run.ctx,
-        run.options.personalMode !== true,
-      )
-    : { toDelete: [], toTombstone: [], refusedStale: [] };
-  const decommissionPlan =
-    (run.options.decommissionPrefixes ?? []).length > 0
-      ? computeDecommissionPlan(
-          run.journal,
-          run.options.decommissionPrefixes ?? [],
-          run.propagateDeletePolicy,
-          new Set([...deletePlan.toDelete.map((item) => item.key), ...deletePlan.toTombstone]),
-        )
-      : [];
-
-  run.emit({
-    type: "plan",
-    filesToDownload: 0,
-    bytesToDownload: 0,
-    filesToUpload: pushPlan.filesToUpload,
-    bytesToUpload: pushPlan.bytesToUpload,
-    filesToSkip: pushPlan.filesToSkip,
-    filesToConflict: 0,
-    filesToDelete: deletePlan.toDelete.length + decommissionPlan.length,
-  });
-
-  if (deletePlan.bulkAsymmetry) {
-    run.emit({
-      type: "delete-refused-bulk-asymmetry",
-      candidates: deletePlan.bulkAsymmetry.candidates,
-      inScope: deletePlan.bulkAsymmetry.inScope,
-      ratio: deletePlan.bulkAsymmetry.ratio,
-      samplePaths: deletePlan.bulkAsymmetry.samplePaths,
-    });
-  }
-
-  return { pushPlan, deletePlan, decommissionPlan };
-}
-
-async function executeUploads(
-  run: PushRunContext,
-  pushPlan: PushPlan,
-  counters: ShareCounters,
-  conflictPaths: string[],
-): Promise<UploadExecutionResult> {
-  const TRANSFER_CONCURRENCY = resolveTransferConcurrency();
-  let conflictPromptChain: Promise<unknown> = Promise.resolve();
-  const resolveConflictSerialized = (
-    info: Parameters<typeof resolveConflict>[0],
-  ): ReturnType<typeof resolveConflict> => {
-    const resolution = conflictPromptChain.then(() =>
-      resolveConflict(info, run.onConflict),
-    );
-    conflictPromptChain = resolution.then(
-      () => undefined,
-      () => undefined,
-    );
-    return resolution;
-  };
-
-  const fileTombstones: Map<string, CompanyTombstone> =
-    run.options.fileTombstones ??
-    (!run.ctx.uid.startsWith("prs_") && run.vaultConfig
-      ? await fetchCompanyTombstones(run.vaultConfig, run.ctx.uid)
-      : new Map<string, CompanyTombstone>());
-
-  const uploadItems: UploadPlanItem[] = [];
-  for (const item of pushPlan.items) {
-    if (item.action === "skip-size-limit") {
-      // A file over the size cap is a permanent, benign skip — NOT an error.
-      // Emitting it as `type: "error"` pushed it into the runner's `errors[]`,
-      // so every watch pass returned exit 2 and the menubar reported an
-      // "auto-sync watcher exited unexpectedly (code=Some(2))" crash on every
-      // tick (the HQ-SYNC-4 flood across user machines). Surface it for visibility, but
-      // do not let it flip the pass to a non-zero exit.
-      let bytes = 0;
-      try {
-        bytes = fs.statSync(item.absolutePath).size;
-      } catch {
-        // Best-effort size for display only; a stat race must not break the sync.
-      }
-      run.emit({
-        type: "skip-size-limit",
-        path: item.relativePath,
-        bytes,
-      });
-      counters.filesSkipped++;
-      continue;
-    }
-    if (item.action === "upload") {
-      if (fileTombstones.size > 0) {
-        const ts = fileTombstones.get(toPosixKey(item.relativePath));
-        if (ts !== undefined) {
-          const entry = run.journal.files[item.relativePath];
-          if (entry && entry.hash === item.localHash) {
-            counters.filesSuppressedByTombstone++;
-            run.emit({
-              type: "upload-suppressed-tombstone",
-              path: item.relativePath,
-              deletedAt: ts.deletedAt,
-            });
-            continue;
-          }
-        }
-      }
-      uploadItems.push(item);
-      continue;
-    }
-    if (item.restamp) {
-      const existing = run.journal.files[item.relativePath];
-      if (existing && existing.hash) {
-        existing.mtimeMs = item.restamp.mtimeMs;
-        existing.size = item.restamp.size;
-      }
-    }
-    counters.filesSkipped++;
-  }
-
-  await primeUploads(
-    run.ctx,
-    uploadItems.map((it) => ({
-      key: it.relativePath,
-      localPath: it.absolutePath,
-      isSymlink: it.kind === "symlink",
-      author: run.options.author,
-    })),
-  );
-  // Warm the GET presigns the per-item conflict HEAD (remoteMeta) reuses, so a
-  // large upload set doesn't mint one presign per HEAD and burst/trip the
-  // presign breaker. Mirrors the new-files + tombstone pre-primes on the pull.
-  await primeObjectTransport(
-    run.ctx,
-    "get",
-    uploadItems.map((it) => it.relativePath),
-  );
-
-  let aborted = false;
-  let abortFlightConflictPaths: string[] = [];
-
-  const processUploadItem = async (item: UploadPlanItem): Promise<void> => {
-    if (aborted) return;
-    const { absolutePath, relativePath, localHash } = item;
-
-    // Cloud-authoritative paths (server-regenerated: company-brief.md, board.json,
-    // ontology/ signals/ sources/) are PULL-WINS and server-owned. The push leg must
-    // NEVER upload the local copy over them — not just on a two-sided conflict, but on
-    // ANY divergence, including a one-sided local change. A stale local mirror (e.g. a
-    // second HQ root that shares this machine's sync journal) would otherwise read as
-    // `localChanged && !remoteChanged`, slip past the conflict-scoped guard below, and
-    // rewind the server's value — the `.last-run` watermark clobber. Skip before HEAD.
-    // board.json is the one push-side exception: local board appends are
-    // legitimate, but must flow through the conditional PUT fence below. It
-    // remains cloud-authoritative on pull so server automation still wins a
-    // pull conflict.
-    if (relativePath !== "board.json" && isCloudAuthoritative(relativePath)) {
-      run.emit({ type: "reconciled", path: relativePath, direction: "push" });
-      counters.filesSkipped++;
-      return;
-    }
-
-    if (run.vaultConfig && isExpiringSoon(run.ctx.expiresAt)) {
-      run.ctx = await refreshEntityContext(run.companyRef, run.vaultConfig);
-    }
-
-    let remoteMeta: Awaited<ReturnType<typeof headRemoteFile>>;
-    try {
-      remoteMeta = await headRemoteFile(run.ctx, relativePath);
-    } catch (headErr) {
-      if (isAccessDenied(headErr)) {
-        run.scopeExcludedSet.add(relativePath);
-        return;
-      }
-      throw headErr;
-    }
-    // Journal entry for this key (if any). Used both for 3-way conflict
-    // classification and for the write fence below: Prefer last-synced
-    // `remoteEtag` over live HEAD so a peer-advanced object cannot be
-    // silently LWW-overwritten by a journaled stale local body (Ace-shaped
-    // vault regression 2026-08-03).
-    const journalEntry = run.journal.files[relativePath];
-
-    if (remoteMeta) {
-      const localChanged = !!journalEntry && journalEntry.hash !== localHash;
-      const remoteChanged = !!journalEntry && hasRemoteChanged(remoteMeta, journalEntry);
-
-      let isFreshCollision = false;
-      let freshContentConverged = false;
-      if (!journalEntry && item.kind === "symlink") {
-        isFreshCollision = true;
-      } else if (!journalEntry && item.kind === "file") {
-        const remoteDiffers = await remoteContentDiffers(
-          run.ctx,
-          relativePath,
-          localHash,
-          run.hqRoot,
-        );
-        if (remoteDiffers) {
-          isFreshCollision = true;
-        } else {
-          freshContentConverged = true;
-        }
-      }
-
-      if (freshContentConverged) {
-        const lstat = fs.lstatSync(absolutePath);
-        updateEntry(
-          run.journal,
-          relativePath,
-          localHash,
-          lstat.size,
-          "up",
-          absolutePath,
-          {
-            remoteEtag: remoteMeta.etag,
-            mtimeMs: lstat.mtimeMs,
-            kind: item.kind,
-          },
-        );
-        run.emit({ type: "reconciled", path: relativePath, direction: "push" });
-        counters.filesSkipped++;
-        return;
-      }
-
-      // `localDiverges` means a prior pull-keep stamped the remote etag for
-      // re-fire silence (#137) while local never matched that remote. The
-      // journal-baseline If-Match fence alone would SUCCEED when remote is
-      // still at that etag, silently promoting the divergent local to write
-      // authority. Route through conflict (keep/abort/overwrite) instead.
-      const divergentLocalHonesty = !!journalEntry?.localDiverges;
-
-      if ((localChanged && remoteChanged) || isFreshCollision || divergentLocalHonesty) {
-        // Cloud-authoritative paths are already skipped at the top of
-        // processUploadItem (before HEAD), so anything reaching here is a genuine
-        // conflict on a client-owned file.
-        conflictPaths.push(relativePath);
-
-        const resolution = await resolveConflictSerialized({
-          path: relativePath,
-          localHash,
-          remoteModified: remoteMeta.lastModified,
-          direction: "push",
-        });
-
-        run.emit({
-          type: "conflict",
-          path: relativePath,
-          direction: "push",
-          resolution,
-        });
-
-        if (resolution === "abort") {
-          aborted = true;
-          abortFlightConflictPaths = [...conflictPaths];
-          return;
-        }
-        if (resolution === "keep" || resolution === "skip") {
-          if (isFreshCollision) {
-            await writePushConflictMirror(run, item, normalizeEtag(remoteMeta.etag));
-          }
-          counters.filesSkipped++;
-          return;
-        }
-        // overwrite: fall through to conditional PUT (or unfenced retry on 412).
-      }
-    }
-
-    if (aborted) return;
-
-    // Write fence: when remote exists, prefer last-synced journal remoteEtag
-    // over live HEAD so a peer-advanced object fails closed (412 → keep/
-    // abort/overwrite). Live-HEAD If-Match alone only covers HEAD→PUT TOCTOU.
-    // When remote is missing (HEAD null), always create-fence with
-    // If-None-Match:* — even if the journal still carries a stale remoteEtag
-    // from a prior sync (deleted key recreation under keep). Using journal
-    // If-Match against a missing object cannot succeed and false-conflicts.
-    // Legacy entries without remoteEtag fall back to live HEAD (prior behavior).
-    const precondition: PutPrecondition = remoteMeta
-      ? journalEntry?.remoteEtag
-        ? { ifMatch: journalEntry.remoteEtag }
-        : { ifMatch: remoteMeta.etag }
-      : { ifNoneMatch: "*" };
-
-    const performUpload = async (pc: PutPrecondition | undefined): Promise<void> => {
-      const isSymlinkUpload = item.kind === "symlink";
-      const lstat = fs.lstatSync(absolutePath);
-      const size = isSymlinkUpload ? 0 : lstat.size;
-      const mtimeMs = lstat.mtimeMs;
-
-      const { etag } = isSymlinkUpload
-        ? await uploadSymlink(run.ctx, item.target, relativePath, run.options.author, pc)
-        : await uploadFile(run.ctx, absolutePath, relativePath, run.options.author, pc);
-
-      updateEntry(
-        run.journal,
-        relativePath,
-        localHash,
-        size,
-        "up",
-        absolutePath,
-        { remoteEtag: etag, mtimeMs, kind: item.kind },
-      );
-      if (run.message) {
-        run.journal.files[relativePath] = {
-          ...run.journal.files[relativePath],
-          message: run.message,
-        } as JournalFileEntry & { message: string };
-      }
-
-      counters.filesUploaded++;
-      counters.bytesUploaded += size;
-      run.emit({
-        type: "progress",
-        path: relativePath,
-        bytes: size,
-        ...(run.message ? { message: run.message } : {}),
-      });
-    };
-
-    try {
-      await performUpload(precondition);
-    } catch (err) {
-      if (err instanceof VaultAuthError) throw err;
-      if (isPreconditionFailed(err)) {
-        conflictPaths.push(relativePath);
-        const resolution = await resolveConflictSerialized({
-          path: relativePath,
-          localHash,
-          direction: "push",
-        });
-        run.emit({
-          type: "conflict",
-          path: relativePath,
-          direction: "push",
-          resolution,
-        });
-        if (resolution === "abort") {
-          aborted = true;
-          abortFlightConflictPaths = [...conflictPaths];
-          return;
-        }
-        if (resolution === "overwrite") {
-          try {
-            await performUpload(undefined);
-          } catch (retryErr) {
-            if (retryErr instanceof VaultAuthError) throw retryErr;
-            run.emit({
-              type: "error",
-              path: relativePath,
-              message: describeError(retryErr),
-            });
-          }
-          return;
-        }
-        await writePushConflictMirror(
-          run,
-          item,
-          remoteMeta ? normalizeEtag(remoteMeta.etag) : "",
-        );
-        counters.filesSkipped++;
-        return;
-      }
-      if (isAccessDenied(err)) {
-        run.scopeExcludedSet.add(relativePath);
-        return;
-      }
-      run.emit({
-        type: "error",
-        path: relativePath,
-        message: describeError(err),
-      });
-    }
-  };
-
-  const workerErrors: Error[] = [];
-  {
-    const queue = [...uploadItems];
-    const inFlight: Set<Promise<unknown>> = new Set();
-    while (queue.length > 0 || inFlight.size > 0) {
-      while (!aborted && inFlight.size < TRANSFER_CONCURRENCY && queue.length > 0) {
-        const item = queue.shift()!;
-        const p: Promise<void> = processUploadItem(item)
-          .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));
-      } else {
-        break;
-      }
-    }
-  }
-
-  return { aborted, abortFlightConflictPaths, workerErrors };
-}
-
-async function writePushConflictMirror(
-  run: PushRunContext,
-  item: UploadPlanItem,
-  remoteHash: string,
-): Promise<void> {
-  try {
-    const detectedAt = new Date().toISOString();
-    const machineId = readShortMachineId(run.hqRoot);
-    const originalRelative = vaultKeyForLocalPath(run.hqRoot, item.absolutePath);
-    const conflictRelative = buildConflictPath(
-      originalRelative,
-      detectedAt,
-      machineId,
-    );
-    const conflictAbs = localPathForVaultKey(run.hqRoot, conflictRelative);
-    if (!isMaterializationPathStillContained(run.syncRoot, conflictAbs)) {
-      run.emit({
-        type: "error",
-        path: item.relativePath,
-        message: "conflict mirror skipped: local parent escaped the sync root",
-      });
-    } else {
-      await downloadFile(run.ctx, item.relativePath, conflictAbs);
-      appendConflictEntry(run.hqRoot, {
-        id: buildConflictId(originalRelative, detectedAt),
-        originalPath: originalRelative,
-        conflictPath: conflictRelative,
-        detectedAt,
-        side: "push",
-        machineId,
-        localHash: item.localHash,
-        remoteHash,
-      });
-    }
-  } catch (mirrorErr) {
-    if (mirrorErr instanceof VaultAuthError) throw mirrorErr;
-    run.emit({
-      type: "error",
-      path: item.relativePath,
-      message: "conflict mirror write failed: " + describeError(mirrorErr),
-    });
-  }
-}
-
-async function executeDeletes(
-  run: PushRunContext,
-  deletePlan: DeletePlan,
-  decommissionPlan: string[],
-  counters: ShareCounters,
-  filesRefusedStalePaths: string[],
-  pathResults: SharePathResult[],
-): Promise<void> {
-  const deleteItems = [
-    ...deletePlan.toDelete.map((item) => ({ ...item, decommission: false })),
-    ...decommissionPlan.map((key) => ({ key, intentVersion: null, decommission: true })),
-  ];
-  const deleteKeys = deleteItems.map((item) => item.key);
-  await primeObjectTransport(run.ctx, "delete", deleteKeys);
-  for (const item of deleteItems) {
-    const { key: relativePath } = item;
-    if (run.vaultConfig && isExpiringSoon(run.ctx.expiresAt)) {
-      run.ctx = await refreshEntityContext(run.companyRef, run.vaultConfig);
-    }
-    try {
-      const entry = run.journal.files[relativePath];
-      // Last-second absence re-check. Applies to EVERY propagated delete,
-      // intent-backed or etag-only: a pull leg or the user can recreate the
-      // file between planning and applying, and deleting it remotely then
-      // destroys a file that exists locally right now. This used to sit inside
-      // the intent-version check, which meant it was skipped for any item
-      // carrying `intentVersion: null` — harmless while that only covered
-      // litter and decommission, but not once etag-only candidates travel that
-      // way too.
-      //
-      // Codec boundary: journal keys are canonical; the probe must use the
-      // ENCODED local path or a win32 colon key always looks absent (a raw `:`
-      // name can never exist on disk) and the remote delete proceeds while the
-      // encoded local file is still present.
-      const recreatedLocally =
-        !item.decommission &&
-        !isLocallyAbsent(localPathForVaultKey(run.syncRoot, relativePath));
-      const intentChanged =
-        !item.decommission &&
-        item.intentVersion !== null &&
-        (!hasCurrentLocalDeleteIntent(entry) ||
-          entry!.localDeleteIntent!.version !== item.intentVersion);
-      if (recreatedLocally || intentChanged) {
-        if (entry?.localDeleteIntent) {
-          delete entry.localDeleteIntent;
-        }
-        const refusalReason = recreatedLocally
-          ? ("recreated-locally" as const)
-          : ("intent-changed" as const);
-        counters.filesRefusedStale++;
-        if (filesRefusedStalePaths.length < REFUSED_STALE_PATH_CAP) {
-          filesRefusedStalePaths.push(relativePath);
-        }
-        run.emit({
-          type: "delete-refused-stale-etag",
-          path: relativePath,
-          journalEtag: entry?.remoteEtag ?? "<missing-delete-intent>",
-          remoteEtag: "<not-checked>",
-          reason: refusalReason,
-        });
-        pathResults.push({
-          path: relativePath,
-          status: "refused",
-          operation: "delete",
-          reason: refusalReason,
-        });
-        continue;
-      }
-      const size = entry?.size ?? 0;
-      await deleteRemoteFile(run.ctx, relativePath);
-      removeEntry(run.journal, relativePath);
-      counters.filesDeleted++;
-      run.emit({
-        type: "progress",
-        path: relativePath,
-        bytes: size,
-        deleted: true,
-      });
-      pathResults.push({
-        path: relativePath,
-        status: "accepted",
-        operation: "delete",
-      });
-    } catch (err) {
-      if (err instanceof VaultAuthError) throw err;
-      run.emit({
-        type: "error",
-        path: relativePath,
-        message: describeError(err),
-      });
-      pathResults.push({
-        path: relativePath,
-        status: "refused",
-        operation: "delete",
-        reason: "transfer-error",
-      });
-    }
-  }
-  for (const relativePath of deletePlan.toTombstone) {
-    const localPath = localPathForVaultKey(run.syncRoot, relativePath);
-    try {
-      const lstat = fs.lstatSync(localPath);
-      const entry = run.journal.files[relativePath];
-      if (lstat.isFile()) {
-        const localHash = hashFile(localPath);
-        if (entry?.hash && entry.hash !== localHash) {
-          run.emit({
-            type: "error",
-            path: relativePath,
-            message:
-              "scope-invalid tombstone skipped: local doubled-tree copy diverged from journal",
-          });
-          continue;
-        }
-        fs.unlinkSync(localPath);
-      } else if (lstat.isSymbolicLink()) {
-        const target = readlinkOrNull(localPath);
-        if (target === null) {
-          run.emit({
-            type: "not-shipped",
-            reason: "unreadable-link",
-            count: 1,
-            samplePaths: [relativePath],
-          });
-          continue;
-        }
-        const localHash = hashSymlinkTarget(target);
-        if (entry?.hash && entry.hash !== localHash) {
-          run.emit({
-            type: "error",
-            path: relativePath,
-            message:
-              "scope-invalid tombstone skipped: local doubled-tree copy diverged from journal",
-          });
-          continue;
-        }
-        fs.unlinkSync(localPath);
-      }
-    } 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: relativePath,
-          message: `tombstone unlink failed: ${
-            err instanceof Error ? err.message : String(err)
-          }`,
-        });
-        continue;
-      }
-    }
-    removeEntry(run.journal, relativePath);
-    counters.filesTombstoned++;
-    run.emit({
-      type: "progress",
-      path: relativePath,
-      bytes: 0,
-      deleted: true,
-      message: "tombstone (remote already 404)",
-    });
-    pathResults.push({
-      path: relativePath,
-      status: "accepted",
-      operation: "tombstone",
-    });
-  }
-  const decommissionedSet =
-    decommissionPlan.length > 0 ? new Set(decommissionPlan) : null;
-  for (const refused of deletePlan.refusedStale) {
-    if (decommissionedSet && decommissionedSet.has(refused.key)) continue;
-    counters.filesRefusedStale++;
-    if (filesRefusedStalePaths.length < REFUSED_STALE_PATH_CAP) {
-      filesRefusedStalePaths.push(refused.key);
-    }
-    run.emit({
-      type: "delete-refused-stale-etag",
-      path: refused.key,
-      journalEtag: refused.journalEtag,
-      remoteEtag: refused.remoteEtag,
-      reason: refused.reason,
-    });
-    pathResults.push({
-      path: refused.key,
-      status: "refused",
-      operation: "delete",
-      reason: refused.reason,
-    });
-  }
-}
-
-function finalizeShareJournal(run: PushRunContext): void {
-  run.journal.lastSync = new Date().toISOString();
-  writeJournal(run.journalSlug, run.journal);
-
-  if (run.excludedSet.size > 0) {
-    const samplePaths: string[] = [];
-    for (const p of run.excludedSet) {
-      samplePaths.push(p);
-      if (samplePaths.length >= 10) break;
-    }
-    run.emit({
-      type: "personal-vault-out-of-policy",
-      count: run.excludedSet.size,
-      samplePaths,
-      byId: { ...run.excludedById },
-    });
-  }
-
-  if (run.scopeExcludedSet.size > 0) {
-    const samplePaths: string[] = [];
-    for (const p of run.scopeExcludedSet) {
-      samplePaths.push(p);
-      if (samplePaths.length >= 10) break;
-    }
-    run.emit({
-      type: "scope-excluded",
-      count: run.scopeExcludedSet.size,
-      samplePaths,
-    });
-  }
-
-  if (run.ignoreExcludedSet.size > 0) {
-    const samplePaths: string[] = [];
-    for (const p of run.ignoreExcludedSet) {
-      samplePaths.push(p);
-      if (samplePaths.length >= 10) break;
-    }
-    run.emit({
-      type: "ignore-excluded",
-      count: run.ignoreExcludedSet.size,
-      totalExcluded: run.ignoreExcludedTotal.value,
-      samplePaths,
-    });
-  }
-
-  emitUnreachablePathEvent(run);
-
-  if (run.linkedSubtreeSet.size > 0) {
-    run.emit({
-      type: "not-shipped",
-      reason: "linked-subtree",
-      count: run.linkedSubtreeSet.size,
-      samplePaths: sampleSet(run.linkedSubtreeSet),
-    });
-  }
-}
-
-/**
- * Which unreachable named paths are FATAL under the run's policy.
- *
- * Under the default `"error"` policy only `"outside-company"` is fatal: the
- * entry is sitting on disk and the resolver refused to place it under the
- * company folder, which is precisely the "exists locally but is unreachable by
- * the resolver" case the report asks to turn into an error, and it cannot
- * happen for an internal walk root (a company folder is trivially inside
- * itself).
- *
- * `"missing"` stays a warn-skip — recorded on `ShareResult.unreachablePaths`
- * and surfaced by the `not-shipped` event, but never fatal. Bulk callers plan
- * one push leg per MEMBERSHIP (`hq sync push --all`), including companies whose
- * folder was never materialized locally; throwing there would turn "you haven't
- * pulled that company yet" into a hard failure of an unrelated multi-company
- * push. Same reasoning for a watcher path deleted between the event and the
- * push. Those callers get the loud report without the regression.
- *
- * `"warn"` makes nothing fatal, for callers whose paths are internal walk roots
- * end to end (the background sync runner).
- */
-function collectFatalUnreachablePaths(
-  run: PushRunContext,
-): Map<string, UnreachablePathReason> {
-  const fatal = new Map<string, UnreachablePathReason>();
-  if (run.options.unreachablePathPolicy === "warn") return fatal;
-  for (const [namedPath, reason] of run.unreachablePaths) {
-    if (reason === "outside-company") fatal.set(namedPath, reason);
-  }
-  return fatal;
-}
-
-/**
- * Emit the `not-shipped` / `unreachable-path` event for a run, if any named
- * path went unshipped. Shared by BOTH policies so the operator sees the same
- * report either way: the fail-fast path emits it immediately before throwing
- * (the journal finalizer never runs on a throw), and the `"warn"` path emits it
- * from the finalizer at the end of a successful run. Exactly one of those two
- * call sites can fire per run, so the event is never duplicated.
- */
-function emitUnreachablePathEvent(run: PushRunContext): void {
-  if (run.unreachablePaths.size === 0) return;
-  const unreadableLinks: string[] = [];
-  const unreachablePaths: string[] = [];
-  for (const [namedPath, reason] of run.unreachablePaths) {
-    (reason === "unreadable-link" ? unreadableLinks : unreachablePaths).push(namedPath);
-  }
-  if (unreachablePaths.length > 0) {
-    run.emit({
-      type: "not-shipped",
-      reason: "unreachable-path",
-      count: unreachablePaths.length,
-      samplePaths: unreachablePaths.slice(0, 10),
-    });
-  }
-  if (unreadableLinks.length > 0) {
-    run.emit({
-      type: "not-shipped",
-      reason: "unreadable-link",
-      count: unreadableLinks.length,
-      samplePaths: unreadableLinks.slice(0, 10),
-    });
-  }
-}
-
-/** First up-to-`limit` members of an iterable, for bounded event payloads. */
-function sampleSet(set: Iterable<string>, limit = 10): string[] {
-  const sample: string[] = [];
-  for (const value of set) {
-    sample.push(value);
-    if (sample.length >= limit) break;
-  }
-  return sample;
-}
-
-function throwUploadWorkerErrors(workerErrors: Error[]): void {
-  if (workerErrors.length > 0) {
-    const first = workerErrors[0]!;
-    if (workerErrors.length > 1) {
-      first.message =
-        first.message +
-        " (and " +
-        (workerErrors.length - 1) +
-        " more upload-worker errors)";
-    }
-    throw first;
-  }
-}
-
-function buildShareResult(
-  run: PushRunContext,
-  counters: ShareCounters,
-  filesRefusedStalePaths: string[],
-  conflictPaths: string[],
-  pathResults: SharePathResult[],
-  aborted: boolean,
-): ShareResult {
-  return {
-    filesUploaded: counters.filesUploaded,
-    bytesUploaded: counters.bytesUploaded,
-    filesSkipped: counters.filesSkipped,
-    filesDeleted: counters.filesDeleted,
-    filesTombstoned: counters.filesTombstoned,
-    filesRefusedStale: counters.filesRefusedStale,
-    filesRefusedStalePaths,
-    filesSuppressedByTombstone: counters.filesSuppressedByTombstone,
-    filesExcludedByPolicy: run.excludedSet.size,
-    filesExcludedByScope: run.scopeExcludedSet.size,
-    filesExcludedByIgnore: run.ignoreExcludedSet.size,
-    unreachablePaths: [...run.unreachablePaths.keys()],
-    linkedSubtreesNotShipped: [...run.linkedSubtreeSet],
-    conflictPaths,
-    pathResults,
-    aborted,
-  };
-}
-
-/**
- * Default human-readable share output. Preserves the exact format the CLI
- * emitted before `onEvent` was added — tty users see no change.
- */
-function defaultConsoleLogger(event: SyncProgressEvent): void {
-  if (event.type === "plan") {
-    if (event.filesToUpload > 0) {
-      console.log(
-        `Plan: ${event.filesToUpload} to upload (${event.bytesToUpload} bytes), ${event.filesToSkip} unchanged`,
-      );
-    }
-  } else if (event.type === "progress") {
-    if (event.deleted) {
-      // Append `message` when present (e.g. tombstone events carry
-      // "tombstone (remote already 404)"). Without this, tombstones and
-      // real deletes render byte-identically in the tty stream, and
-      // operators have no way to distinguish from logs alone.
-      const suffix = event.message ? ` — ${event.message}` : "";
-      console.log(`  ✗ ${event.path} (deleted)${suffix}`);
-    } else if (event.message) {
-      console.log(`  ✓ ${event.path} — "${event.message}"`);
-    } else {
-      console.log(`  ✓ ${event.path}`);
-    }
-  } else if (event.type === "conflict") {
-    console.error(
-      `  ⚠ conflict (${event.direction}): ${event.path} — ${event.resolution}`,
-    );
-  } else if (event.type === "error") {
-    console.error(`  ✗ ${event.path} — ${event.message}`);
-  } else if (event.type === "delete-refused-stale-etag") {
-    // Branch on `reason`, not on the sentinel etag strings, so legacy
-    // entries render with a clear explanation instead of "<legacy-no-etag>"
-    // leaking into operator-visible output.
-    if (event.reason === "legacy-no-etag") {
-      console.error(
-        `  ⚠ no-etag-on-record, kept on remote: ${event.path} (journal entry predates etag tracking)`,
-      );
-    } else if (event.reason === "bulk-asymmetry") {
-      // The one-shot summary below carries the count + bypass instructions.
-      // Per-key lines stay compact so a 100-candidate refusal doesn't bury
-      // the summary banner.
-      console.error(`  ⚠ bulk-asymmetry refusal, kept on remote: ${event.path}`);
-    } else if (event.reason === "missing-delete-intent") {
-      // NEITHER etag is meaningful here: no HEAD was issued, so `remoteEtag`
-      // is the `<not-checked>` sentinel, and `journalEtag` is the entry's
-      // real recorded etag. Printing them under the `stale-etag` wording
-      // (which this branch used to fall through to) reads as an etag
-      // conflict and has repeatedly sent operators chasing a currency bug
-      // that does not exist — the actual cause is that no watcher observed
-      // the removal, so no delete authorization was ever recorded.
-      console.error(
-        `  ⚠ no-delete-authorization, kept on remote: ${event.path} ` +
-          `(the sync watcher did not observe this removal, so the delete was never authorized)`,
-      );
-    } else if (event.reason === "recreated-locally") {
-      console.error(
-        `  ⚠ recreated-locally, kept on remote: ${event.path} ` +
-          `(the file exists locally again, so the delete was abandoned)`,
-      );
-    } else if (event.reason === "divergent-local") {
-      // Same trap as above — `remoteEtag` is `<not-checked>`. The entry's
-      // recorded etag was stamped only to silence a re-fired conflict; the
-      // local copy never matched it, so propagating the delete would destroy
-      // divergent remote work.
-      console.error(
-        `  ⚠ divergent-local, kept on remote: ${event.path} ` +
-          `(the local copy never matched the recorded remote version; pull to reconcile first)`,
-      );
-    } else {
-      console.error(
-        `  ⚠ stale-etag, kept on remote: ${event.path} (journal=${event.journalEtag}, remote=${event.remoteEtag})`,
-      );
-    }
-  } else if (event.type === "delete-refused-bulk-asymmetry") {
-    const pct = (event.ratio * 100).toFixed(1);
-    console.error(
-      `  ⚠ bulk-asymmetry circuit-breaker tripped: ${event.candidates}/${event.inScope} in-scope journal entries (${pct}%) are missing locally.\n` +
-      `    Refusing to propagate deletes — this looks like a local-mirror loss (moved hqRoot, partial restore, fresh clone, unmounted volume, accidental rm) rather than an intentional cleanup.\n` +
-      `    Sample refused paths: ${event.samplePaths.slice(0, 5).join(", ")}${event.samplePaths.length > 5 ? ", …" : ""}\n` +
-      `    To proceed anyway: re-run with HQ_SYNC_DELETE_BULK_OVERRIDE=1 (or propagateDeletePolicy:"all").`,
-    );
-  } else if (event.type === "skip-invalid-scoped-key") {
-    console.warn(
-      `  ! ${event.path} skipped — 'companies/'-prefixed key is invalid in a company-scoped vault (stale doubled local tree? remove the inner companies/<slug> copy)`,
-    );
-  } else if (event.type === "ignore-excluded") {
-    // The "not silent" surface: an ignore rule dropped content that doesn't
-    // look like expected build/VCS/cache noise, so it never reached the vault.
-    // Surface it as a WARN naming the paths so an over-broad exclusion is
-    // observable rather than invisible (DEV-1791 / feedback_b9dfc7ae).
-    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 === "not-shipped") {
-    // The other "not silent" surface: content the walk saw but chose not to
-    // ship. Name it so a "Pushed 0 file(s)" is never a silent no-op.
-    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`);
-    }
-  }
-}
-
-/**
- * One entry produced by collectFiles/walkDir. Files describe regular
- * payloads that get hashed + size-checked + uploaded via uploadFile;
- * symlinks describe link records whose target string flows through
- * uploadSymlink as user metadata. Walked-dir traversal NEVER descends
- * into a symlink — directory symlinks are recorded as link entries and
- * left at that, so following them never duplicates content into the
- * wrong vault path (the same topology safety the legacy walker provided
- * by accident of Dirent.isFile() returning false for links).
- */
-type CollectedEntry =
-  | { kind: "file"; absolutePath: string; relativePath: string }
-  | { kind: "symlink"; absolutePath: string; relativePath: string; target: string };
-
-/**
- * Optional visibility callbacks for {@link collectFiles} / {@link walkDir}.
- * They turn two previously-SILENT outcomes into surfaced signals — without
- * changing WHAT gets uploaded (feedback_258e4a86 / feedback_a51cb63d):
- *
- *   - `onUnreachablePath`: a path that cannot be shipped. It is normally the
- *     caller's explicit spelling (`"outside-company"` or `"missing"`), and is
- *     the company-relative key for an unreadable link discovered during a
- *     directory walk (`"unreadable-link"`). Pre-fix this was a bare
- *     `console.error` warn-skip that still let the push report "Pushed 0 file(s)"
- *     — a false success. The caller can now turn a non-empty set into a real
- *     error / nonzero exit.
- *
- *     SPELLING CONTRACT: resolver outcomes use the caller's ORIGINAL token,
- *     verbatim — never the resolved absolute path, and never normalized. A
- *     relative `knowledge/agents/x.md` is reported as `knowledge/agents/x.md`;
- *     an absolute path is reported absolute because that is what was passed.
- *     An unreadable link discovered during a recursive walk instead uses its
- *     company-relative vault key, because it has no separate caller token.
- *     This keeps UI output actionable without exposing host-specific paths.
- *   - `onLinkedSubtree`: a directory symlink recorded as a link but NOT
- *     descended because its target resolves OUTSIDE the company folder (e.g.
- *     `companies/{co}/knowledge` → `repos/private/knowledge-{co}/`). The link's
- *     contents ship via their own repo, not the vault; reporting it stops files
- *     created under such a link from vanishing from every push bucket silently.
- */
-interface CollectHooks {
-  onUnreachablePath?: (namedPath: string, reason: UnreachablePathReason) => void;
-  onLinkedSubtree?: (rel: string) => void;
-}
-
-/**
- * Resolve a caller-supplied push path to an absolute path.
- *
- * Relative paths were historically resolved against `hqRoot` ONLY, so a
- * company-relative spelling like `knowledge/agents/x.md` became
- * `<hqRoot>/knowledge/agents/x.md` and reported "does not exist" no matter the
- * caller's cwd or the company being pushed (feedback_258e4a86 /
- * feedback_a51cb63d — "there is no path spelling that reaches the file").
- *
- * PRECEDENCE (documented contract, asserted by test): `hqRoot` → `syncRoot`
- * (the company folder) → `cwd`. hqRoot stays FIRST so this change is purely
- * ADDITIVE to the legacy behavior: every relative spelling that resolved
- * pre-fix still resolves to exactly the same file, and the two new bases only
- * catch spellings that previously resolved to nothing. Probing cwd first would
- * silently re-point existing callers (a `knowledge/` directory in the shell's
- * cwd would win over the hq-root one), which is a behavior change no reporter
- * asked for. Fall back to the hqRoot candidate so a genuine typo still surfaces
- * the unchanged "does not exist" diagnostic. Absolute paths are returned
- * verbatim.
- *
- * `cwd` is an explicit injected parameter (defaulting to `process.cwd()`)
- * rather than an ambient read, so resolution is deterministic and testable
- * without mutating process state.
- */
-function resolveNamedPath(
-  p: string,
-  hqRoot: string,
-  syncRoot: string,
-  cwd: string = process.cwd(),
-): string {
-  if (path.isAbsolute(p)) return p;
-  const hqRootCandidate = path.resolve(hqRoot, p);
-  const candidates = [
-    hqRootCandidate,
-    path.resolve(syncRoot, p),
-    path.resolve(cwd, p),
-  ];
-  for (const candidate of candidates) {
-    try {
-      fs.lstatSync(candidate);
-      // An hqRoot hit outside the company folder would be rejected by
-      // collectFiles as outside-company; skip it so a valid company-relative
-      // spelling can win (Codex P2 — common `knowledge/` homonym case).
-      if (candidate === hqRootCandidate && !isWithin(syncRoot, candidate)) {
-        continue;
-      }
-      return candidate;
-    } catch {
-      // Base did not resolve to an on-disk entry — try the next one.
-    }
-  }
-  return hqRootCandidate;
-}
-
-/**
- * Containment check for a regular file or directory that tolerates a symlinked
- * ANCESTOR. `isWithin` canonicalizes the full child via `realpathSync`, so a
- * path reached through a symlinked ancestor (`companies/{co}/knowledge` →
- * `repos/private/knowledge-{co}/`) resolves OUTSIDE the company folder and was
- * rejected as "outside company folder" — even though its logical path is
- * in-tree and `vaultKeyForLocalPath` (also lexical) derives a correct
- * company-namespaced key for it. Accept when the LEXICAL path is inside
- * (honoring the same logical topology the vault key uses) OR the realpath is
- * inside (preserving `isWithin`'s macOS APFS case-insensitivity tolerance).
- *
- * The lexical arm carries TWO bounds, because it is the only place where a
- * path's bytes and its vault key come from different trees:
- *
- *  1. `hqRoot` — the realpath must still land inside the HQ tree, so a
- *     symlinked ancestor pointing at `/etc` cannot upload arbitrary machine
- *     state under a company-namespaced key.
- *  2. The TENANT — the realpath must not land inside another company's bytes
- *     (`foreignTenantRoots`). The hqRoot bound alone is NOT sufficient and
- *     must never be mistaken for a tenant boundary: hqRoot CONTAINS every
- *     other company, so `companies/acme/knowledge → companies/other/secret`
- *     (or → `repos/private/knowledge-other`, the linked-repo topology) is
- *     lexically inside acme and really inside HQ, and would upload the other
- *     tenant's bytes into acme's bucket under the key `knowledge/…`.
- *
- * The motivating topology (`companies/{co}/knowledge` →
- * `repos/private/knowledge-{co}`) satisfies both, so it is unaffected. A link
- * that escapes HQ, or one that reaches another tenant, is refused — and under
- * the default unreachable-path policy, refused LOUDLY rather than warn-skipped.
- *
- * Known limit, stated so it is not mistaken for a guarantee: a foreign tenant's
- * externally-linked subtree can only be recognized while that company's folder
- * is materialized locally and publishes the link. A machine holding
- * `repos/private/knowledge-other` with no `companies/other` folder has no
- * on-disk evidence of the claim, so a link into it is indistinguishable from a
- * link into any other local repo. Ownership metadata (not path shape) is what
- * would close that gap.
- */
-function isWithinLexicalOrReal(
-  parent: string,
-  child: string,
-  hqRoot: string,
-  tenantRootsCache?: Map<string, string[]>,
-): boolean {
-  // Strict arm first: the realpath is genuinely inside the company folder.
-  // This is the overwhelmingly common case, needs no relaxation, and costs no
-  // directory scan.
-  if (isWithin(parent, child)) return true;
-
-  const resolvedChild = path.resolve(child);
-  if (!isPathWithin(path.resolve(parent), resolvedChild)) return false;
-
-  const childReal = realpathSafe(resolvedChild);
-  if (!isWithin(hqRoot, childReal)) return false; // bound 1: escapes HQ
-
-  // NUL-joined: it is the one byte a path cannot contain, so no pair of
-  // (hqRoot, parent) values can collide on the key.
-  const cacheKey = `${hqRoot}\u0000${parent}`;
-  let foreignRoots = tenantRootsCache?.get(cacheKey);
-  if (foreignRoots === undefined) {
-    foreignRoots = foreignTenantRoots(hqRoot, parent);
-    tenantRootsCache?.set(cacheKey, foreignRoots);
-  }
-  for (const foreign of foreignRoots) {
-    if (isPathWithin(foreign, childReal)) return false; // bound 2: other tenant
-  }
-  return true;
-}
-
-/**
- * Depth (in path segments below a company root) at which we look for the
- * directory symlinks a company publishes into its own folder. HQ's linked
- * topologies live at depth 1 (`companies/{co}/knowledge`) and depth 2
- * (`companies/{co}/repos/{name}`); going deeper would turn a containment check
- * into a full-tree walk for no additional coverage.
- */
-const FOREIGN_TENANT_LINK_SCAN_DEPTH = 2;
-
-/**
- * Canonicalized roots that belong to a tenant OTHER than the one being pushed.
- * A lexically-contained path whose realpath lands inside any of these is
- * another company's data wearing this company's key, and must be refused.
- *
- * Two kinds of root are collected per foreign company:
- *   - the company folder itself (`companies/{other}`), and
- *   - the targets of the directory symlinks that folder publishes — HQ's
- *     pattern-2 topology puts a company's knowledge in `repos/private/
- *     knowledge-{other}` and links it in, so the bytes live OUTSIDE every
- *     `companies/` root and a companies-only check would miss them entirely.
- *
- * Only consulted on the rare lexical arm (a path whose realpath is not inside
- * the company folder), never on the ordinary in-tree push, so the directory
- * scan is not on the hot path. Callers may memoize it for the duration of a
- * single collect pass; nothing memoizes it for longer, because the sync runner
- * is long-lived and a stale tenant map fails OPEN — the wrong direction for a
- * boundary whose whole job is to refuse.
- */
-function foreignTenantRoots(hqRoot: string, syncRoot: string): string[] {
-  const companiesDir = path.join(hqRoot, "companies");
-  let entries: fs.Dirent[];
-  try {
-    entries = fs.readdirSync(companiesDir, { withFileTypes: true });
-  } catch {
-    return []; // no companies/ tree here — nothing to be foreign to
-  }
-
-  const activeReal = realpathSafe(syncRoot);
-  const roots: string[] = [];
-  for (const entry of entries) {
-    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
-    const companyRoot = path.join(companiesDir, entry.name);
-    const companyReal = realpathSafe(companyRoot);
-    if (companyReal === activeReal) continue; // this is the tenant being pushed
-    roots.push(companyReal);
-    collectPublishedLinkTargets(companyRoot, companyReal, FOREIGN_TENANT_LINK_SCAN_DEPTH, roots);
-  }
-  return roots;
-}
-
-/**
- * Append the resolved targets of the directory symlinks published under
- * `companyRoot` (down to `depth` levels) into `out`. Targets that resolve back
- * inside the company folder are skipped — they add no reach beyond the root
- * already recorded. Errors are swallowed per entry on purpose: an unreadable
- * sibling directory must narrow what we can prove, never abort the push it is
- * unrelated to.
- */
-function collectPublishedLinkTargets(
-  dir: string,
-  companyReal: string,
-  depth: number,
-  out: string[],
-): void {
-  if (depth <= 0) return;
-  let entries: fs.Dirent[];
-  try {
-    entries = fs.readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return;
-  }
-  for (const entry of entries) {
-    const child = path.join(dir, entry.name);
-    if (entry.isSymbolicLink()) {
-      let real: string;
-      try {
-        real = fs.realpathSync.native(child);
-      } catch {
-        continue; // dangling link claims nothing
-      }
-      try {
-        if (!fs.statSync(real).isDirectory()) continue;
-      } catch {
-        continue;
-      }
-      if (isPathWithin(companyReal, real)) continue; // no reach beyond the root
-      out.push(real);
-    } else if (entry.isDirectory()) {
-      collectPublishedLinkTargets(child, companyReal, depth - 1, out);
-    }
-  }
-}
-
-/**
- * If a recorded directory symlink's target resolves OUTSIDE `syncRoot`, invoke
- * `onLinkedSubtree` so the caller can report that the link's contents were not
- * uploaded to the vault. Fires only for links that (a) resolve to a directory
- * and (b) point outside the company folder — an in-tree link is descended
- * elsewhere, and a dangling or file link has nothing behind it to report.
- */
-function reportLinkedSubtreeIfExternal(
-  linkPath: string,
-  syncRoot: string,
-  relativePath: string,
-  hooks: CollectHooks,
-): void {
-  if (!hooks.onLinkedSubtree) return;
-  let real: string;
-  try {
-    real = fs.realpathSync.native(linkPath); // resolves the link to its target
-  } catch {
-    return; // dangling link — nothing behind it to report
-  }
-  let targetStat: fs.Stats;
-  try {
-    targetStat = fs.statSync(real);
-  } catch {
-    return;
-  }
-  if (!targetStat.isDirectory()) return;
-  if (isWithin(syncRoot, real)) return; // in-tree target: descended elsewhere
-  hooks.onLinkedSubtree(relativePath);
-}
-
-/**
- * Collect files from paths (expanding directories recursively).
- *
- * Remote S3 keys are computed relative to `syncRoot` (companies/{slug}/), not
- * `hqRoot`. Files outside `syncRoot` are skipped with a warning — sharing
- * anything outside a company's folder would leak state into the wrong vault.
- *
- * Symlink classification uses lstat (not stat), so a top-level path that is
- * itself a symlink is recorded as a link record rather than dereferenced.
- * Pre-fix, statSync followed the link and the target's bytes were uploaded
- * under the link's key — silently flattening the link topology.
- */
-function collectFiles(
-  paths: string[],
-  hqRoot: string,
-  syncRoot: string,
-  filter: (p: string, isDir?: boolean) => boolean,
-  hooks: CollectHooks = {},
-): CollectedEntry[] {
-  const results: CollectedEntry[] = [];
-  // Scoped to THIS collect pass and discarded with it: a watcher batch can
-  // name hundreds of paths, and rescanning the companies/ tree for each one
-  // is wasted I/O. A cache that outlived the pass could fail open on a tenant
-  // boundary, so it deliberately does not.
-  const tenantRoots = new Map<string, string[]>();
-
-  for (const p of paths) {
-    const absolutePath = resolveNamedPath(p, hqRoot, syncRoot);
-
-    // Ephemeral artifacts (conflict mirrors) — see EPHEMERAL_PATH_PATTERN doc.
-    // Caller may pass one explicitly; we still refuse to upload it. Basename
-    // check matches the walkDir gate so behavior is identical whether the
-    // mirror is the user-supplied path or found during directory recursion.
-    if (isEphemeralPath(path.basename(absolutePath))) continue;
-
-    // existsSync follows symlinks: a dangling top-level link will report
-    // not-existing and be skipped here. lstatSync below handles the
-    // valid-link case directly without needing the existsSync gate.
-    let lstat: fs.Stats;
-    try {
-      lstat = fs.lstatSync(absolutePath);
-    } catch {
-      console.error(`  Warning: ${p} does not exist, skipping.`);
-      hooks.onUnreachablePath?.(p, "missing");
-      continue;
-    }
-
-    // Containment check is split by entry kind: regular files and
-    // directories use isWithin (which canonicalizes via realpathSync to
-    // tolerate macOS APFS case-insensitivity), but symlinks use the
-    // link's own pathname rather than the link's resolved target. A
-    // valid use case for this asymmetry: a directory symlink whose
-    // target lives outside the company folder (e.g. companies/{co}/
-    // knowledge → repos/private/knowledge-{co}/) — the LINK itself is
-    // inside the company folder and is exactly what we want to record,
-    // but isWithin's realpath would say the resolved target is outside
-    // and reject the share. Recording symlinks rather than following
-    // them is the whole topology contract this fix establishes; the
-    // containment check needs to honor the same semantic.
-    if (lstat.isSymbolicLink()) {
-      if (!isWithinForLink(syncRoot, absolutePath)) {
-        console.error(`  Warning: ${p} is outside company folder, skipping.`);
-        hooks.onUnreachablePath?.(p, "outside-company");
-        continue;
-      }
-      const relativePath = vaultKeyForLocalPath(syncRoot, absolutePath);
-      // Probe the filter with both isDir hints — we don't know whether
-      // the link's target is a file or a directory without
-      // stat-following the link, which we explicitly avoid (it would
-      // re-introduce the dereference behavior this whole change set is
-      // designed to prevent). An `.hqinclude` dir-only pattern like
-      // `companies/*/knowledge/` only matches with isDir=true, so a
-      // single isDir=false probe would silently drop directory
-      // symlinks under allowlist mode (the motivating case for this
-      // whole branch). The filter is pure path lookup with no I/O,
-      // so two calls are free.
-      if (!filter(absolutePath, false) && !filter(absolutePath, true)) continue;
-      const target = readlinkOrNull(absolutePath);
-      if (target === null) {
-        console.error(`  Warning: ${p} is an unreadable symbolic link, skipping.`);
-        hooks.onUnreachablePath?.(p, "unreadable-link");
-        continue;
-      }
-      // A directory symlink whose target lives outside the company folder is
-      // recorded here but never descended — its contents ship via their own
-      // repo, not the vault. Surface it so files created under such a link
-      // don't vanish from every push bucket silently.
-      reportLinkedSubtreeIfExternal(absolutePath, syncRoot, relativePath, hooks);
-      results.push({
-        kind: "symlink",
-        absolutePath,
-        relativePath,
-        target,
-      });
-      continue;
-    }
-
-    if (!isWithinLexicalOrReal(syncRoot, absolutePath, hqRoot, tenantRoots)) {
-      console.error(`  Warning: ${p} is outside company folder, skipping.`);
-      hooks.onUnreachablePath?.(p, "outside-company");
-      continue;
-    }
-
-    if (lstat.isDirectory()) {
-      if (!filter(absolutePath, true)) continue;
-      walkDir(absolutePath, syncRoot, filter, results, hooks);
-    } else if (lstat.isFile()) {
-      const relativePath = vaultKeyForLocalPath(syncRoot, absolutePath);
-      if (filter(absolutePath)) {
-        results.push({ kind: "file", absolutePath, relativePath });
-      }
-    }
-  }
-
-  return results;
-}
-
-function walkDir(
-  dir: string,
-  syncRoot: string,
-  filter: (p: string, isDir?: boolean) => boolean,
-  results: CollectedEntry[],
-  hooks: CollectHooks = {},
-): void {
-  // A frame per open directory preserves the recursive walk's depth-first
-  // ordering without turning a completed subtree into one giant call argument
-  // list. This matters for both operator-visible plan ordering and large trees.
-  const stack: Array<{ dir: string; entries: fs.Dirent[]; index: number }> = [];
-  const enterDirectory = (currentDir: string): void => {
-    if (!fs.existsSync(currentDir)) return;
-    stack.push({
-      dir: currentDir,
-      entries: fs.readdirSync(currentDir, { withFileTypes: true }),
-      index: 0,
-    });
-  };
-
-  enterDirectory(dir);
-  while (stack.length > 0) {
-    const frame = stack[stack.length - 1];
-    if (frame.index >= frame.entries.length) {
-      stack.pop();
-      continue;
-    }
-    const entry = frame.entries[frame.index++];
-    // Ephemeral artifacts (conflict mirrors) are local-only safety backups
-    // that MUST NEVER round-trip to S3. Check basename here so the filter
-    // applies regardless of which company root contains them. See
-    // EPHEMERAL_PATH_PATTERN doc for the full rationale.
-    if (isEphemeralPath(entry.name)) continue;
-    const absolutePath = path.join(frame.dir, entry.name);
-    const isDir = entry.isDirectory();
-
-    // Symlinks need their own filter probe BEFORE the regular gate.
-    // Dirent.isDirectory() returns false for any symlink — even a
-    // directory symlink — so the regular filter call below would use
-    // isDir=false and a dir-only allowlist pattern like
-    // `companies/*/knowledge/` would reject the link before the
-    // record-only branch runs. Probe with both hints; include if
-    // either matches. The filter is pure path lookup with no I/O.
-    if (entry.isSymbolicLink()) {
-      if (!filter(absolutePath, false) && !filter(absolutePath, true)) continue;
-      // Record the link without descending into its target. Following
-      // a directory symlink would re-enter content via a path that
-      // isn't its on-disk home (e.g. companies/{co}/knowledge → repos/
-      // private/knowledge-{co}/), causing per-company knowledge repos
-      // to be uploaded into every vault that links them. Recording
-      // and not following preserves the link topology while avoiding
-      const linkRelative = vaultKeyForLocalPath(syncRoot, absolutePath);
-      // On win32, a Dirent-known link is not sufficient proof that readlink
-      // will succeed (notably for some reparse points). Never fall through to
-      // normal file/directory handling here: doing so would dereference the
-      // link and duplicate its target under this vault key.
-      const target = readlinkOrNull(absolutePath);
-      if (target === null) {
-        console.error(`  Warning: ${linkRelative} is an unreadable symbolic link, skipping.`);
-        hooks.onUnreachablePath?.(linkRelative, "unreadable-link");
-        continue;
-      }
-      // The link is recorded but its (external) target is not descended, so
-      // any files under it are NOT uploaded. Report the subtree so a full
-      // `sync now` no longer drops it from every bucket without a trace.
-      reportLinkedSubtreeIfExternal(absolutePath, syncRoot, linkRelative, hooks);
-      results.push({
-        kind: "symlink",
-        absolutePath,
-        relativePath: linkRelative,
-        target,
-      });
-      continue;
-    }
-
-    // Pass the dir hint so dir-only ignore/include patterns (`foo/`)
-    // resolve correctly for the descent decision.
-    if (!filter(absolutePath, isDir)) continue;
-
-    if (isDir) {
-      enterDirectory(absolutePath);
-    } else if (entry.isFile()) {
-      results.push({
-        kind: "file",
-        absolutePath,
-        relativePath: vaultKeyForLocalPath(syncRoot, absolutePath),
-      });
-    }
-  }
-}
-
-function isWithin(parent: string, child: string): boolean {
-  // Canonicalize both ends so the comparison survives case-insensitive
-  // filesystems (macOS APFS, Windows NTFS): `path.relative('/Users/x/hq',
-  // '/Users/x/HQ/foo')` returns `'../HQ/foo'`, which would falsely report
-  // `child` as outside `parent`. `realpathSync.native` resolves to the
-  // on-disk canonical case so the relative path lands inside.
-  const parentCanon = realpathSafe(parent);
-  const childCanon = realpathSafe(child);
-  const rel = path.relative(parentCanon, childCanon);
-  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
-}
-
-function isPathWithin(parent: string, child: string): boolean {
-  const rel = path.relative(parent, child);
-  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
-}
-
-function realpathSafe(p: string): string {
-  try {
-    return fs.realpathSync.native(p);
-  } catch {
-    return p;
-  }
-}
-
-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 isMaterializationPathStillContained(root: string, localPath: string): boolean {
-  const resolvedRoot = path.resolve(root);
-  const resolvedLocal = path.resolve(localPath);
-  if (!isPathWithin(resolvedRoot, resolvedLocal)) return false;
-
-  let realRoot: string;
-  try {
-    realRoot = fs.realpathSync.native(resolvedRoot);
-  } catch {
-    return false;
-  }
-
-  const existingAncestor = deepestExistingAncestor(path.dirname(resolvedLocal));
-  if (existingAncestor === null) return false;
-  try {
-    const realAncestor = fs.realpathSync.native(existingAncestor);
-    return isPathWithin(realRoot, realAncestor);
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Containment check tailored for symlinks. Canonicalizes the link's
- * PARENT DIR (which is a real dir, not the link), then compares the
- * recombined `parentReal/basename(linkPath)` against `parent`. Skipping
- * the link's own canonicalization means a symlink that points outside
- * `parent` is still considered "inside" so long as the link file itself
- * lives inside — which is exactly the topology we want to upload as a
- * link record without dereferencing.
- *
- * Falls back to `parent` / `path.dirname(linkPath)` literally when
- * realpath throws (e.g. permission denied on a parent), trading a tiny
- * window of macOS-APFS case-sensitivity drift for the more common case
- * of "link lives inside, target lives outside."
- */
-function isWithinForLink(parent: string, linkPath: string): boolean {
-  const parentReal = realpathSafe(parent);
-  const linkParentReal = realpathSafe(path.dirname(linkPath));
-  const candidate = path.join(linkParentReal, path.basename(linkPath));
-  const rel = path.relative(parentReal, candidate);
-  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
-}
-
-/**
- * Resolve each user-supplied share path to a directory under `syncRoot`,
- * returning the company-relative prefix that constrains delete propagation.
- * Files (non-directories) and paths outside the company root are dropped —
- * a delete sweep keyed off a single file or a sibling tree would surprise
- * users who expected deletes to mirror the targeted scope.
- *
- * Returns `[""]` (whole-tree) when any input path resolves to `syncRoot`
- * itself; this is the bidirectional-runner case.
- *
- * Path spellings are resolved with `resolveNamedPath`, the same resolver the
- * upload leg uses, so `hq sync push knowledge/agents` scopes deletes exactly
- * like its absolute equivalent instead of silently resolving nowhere and
- * scoping nothing.
- *
- * Containment, however, deliberately stays on strict realpath `isWithin` and
- * does NOT adopt the upload leg's `isWithinLexicalOrReal` relaxation. The two
- * legs are asymmetric on purpose: the upload leg ships the files it was handed,
- * while a delete scope is a PREFIX that authorizes removing every remote object
- * beneath it. A linked subtree's contents are never walked (`walkDir` does not
- * descend external directory symlinks), so anchoring a delete scope on one
- * would compare an empty local walk against a populated remote prefix and sweep
- * the whole prefix away. Narrow-and-safe beats wide-and-lossy here; the
- * accepted cost is that deletes inside a linked subtree are not propagated,
- * which matches the snapshot semantics `hq sync push` already documents for
- * those paths.
- */
-function resolveDeleteScopeRoots(
-  paths: string[],
-  hqRoot: string,
-  syncRoot: string,
-  explicitRoots: readonly string[] = [],
-): string[] {
-  const prefixes = new Set<string>();
-  for (const root of explicitRoots) {
-    const normalized = root
-      .split("\\")
-      .join("/")
-      .replace(/^\.\/+/, "")
-      .replace(/\/+$/, "");
-    if (
-      normalized === "" ||
-      normalized === "." ||
-      path.posix.isAbsolute(normalized) ||
-      normalized === ".." ||
-      normalized.startsWith("../")
-    ) {
-      continue;
-    }
-    prefixes.add(normalized);
-  }
-  for (const p of paths) {
-    const absolutePath = resolveNamedPath(p, hqRoot, syncRoot);
-    if (!fs.existsSync(absolutePath)) continue;
-    if (!isWithin(syncRoot, absolutePath)) continue;
-    const stat = fs.statSync(absolutePath);
-    if (!stat.isDirectory()) continue;
-    const rel = vaultKeyForLocalPath(syncRoot, absolutePath);
-    if (rel === "" || rel === ".") {
-      return [""];
-    }
-    prefixes.add(rel);
-  }
-  return Array.from(prefixes);
-}
-
-/**
- * Reason a candidate was bucketed into `refusedStale`. Discriminated so
- * consumers (UI, telemetry, the event logger) can branch on intent without
- * string-comparing the placeholder etag value.
- *   - `"stale-etag"`     → currency-gated saw a real etag mismatch (peer
- *                          drift). `journalEtag` and `remoteEtag` are both
- *                          real ETag values.
- *   - `"legacy-no-etag"` → journal entry was written before remoteEtag was
- *                          tracked. `journalEtag` and `remoteEtag` are
- *                          placeholder sentinels — do not display as ETags.
- */
-type RefusedStaleReason =
-  | "stale-etag"
-  | "legacy-no-etag"
-  | "bulk-asymmetry"
-  | "divergent-local"
-  | "missing-delete-intent"
-  | "intent-changed"
-  | "recreated-locally";
-
-/**
- * Bulk-asymmetry circuit-breaker — refuses to convert a suspiciously-large
- * fraction of the in-scope journal entries into remote `DeleteObject` calls.
- *
- * Failure mode this defends against: the local mirror is corrupt
- * (moved hqRoot, partial restore from backup, fresh clone over an inherited
- * `~/.hq/sync-journal.*.json`, unmounted external volume, accidental
- * `rm -rf` of a populated subtree). `computeDeletePlan` walks every journal
- * entry, lstats locally, and any ENOENT is a delete candidate; under
- * `currency-gated` the per-file HEAD passes in the steady state (nobody
- * else rewrote the object) so the delete proceeds. Per-file currency is
- * orthogonal to whole-set health — when a large slice of the mirror is
- * absent at once, the engine should refuse rather than amplify the
- * accident into a mass-DELETE.
- *
- * The guard fires when **both** conditions hold:
- *   - `candidates / inScope >= BULK_ASYMMETRY_RATIO` (default 10%).
- *   - `candidates >= BULK_ASYMMETRY_MIN_ABS` (default 10).
- *
- * `candidates` is the whole prospective destructive set, whether or not each
- * entry carries a current watcher delete-intent. A live watcher stamps one
- * intent per descendant when a directory disappears, so intent presence says
- * nothing about whether the disappearance was deliberate — see the numerator
- * comment in `computeDeletePlan` and the 2026-07-30 incident.
- *
- * The MIN_ABS floor is what lets small intentional deletes through —
- * `rm 1 file` from a 5-entry mirror is 20% but 1 absolute candidate; never
- * tripped. The RATIO is what lets large intentional uploads-then-deletes
- * through — a 10000-entry journal where 50 files were intentionally
- * removed is 0.5%; never tripped.
- *
- * Bypass paths (both intentional opt-outs of safety):
- *   - Env `HQ_SYNC_DELETE_BULK_OVERRIDE=1|true|yes` (case-insensitive). The
- *     rollback knob for the rare legitimate mass-delete; symmetric to
- *     `HQ_SYNC_DELETE_POLICY` as a per-invocation policy override.
- *   - `propagateDeletePolicy: "all"`. The emergency-reconcile policy
- *     already opts out of safety gates (currency check, owned-only).
- *     This guard honors that explicit opt-out.
- *
- * `"owned-only"` and `"currency-gated"` both go through the guard. The
- * `direction === "up"` filter in `owned-only` is no defense once a user
- * has ever run full bidirectional sync (every uploaded file gets
- * direction:'up') — see investigation report
- * `workspace/reports/indigo-vault-mass-delete-debug.md`.
- */
-const BULK_ASYMMETRY_RATIO = 0.10;
-const BULK_ASYMMETRY_MIN_ABS = 10;
-const BULK_ASYMMETRY_SAMPLE_CAP = 10;
-
-function isBulkAsymmetryOverride(): boolean {
-  const v = (process.env.HQ_SYNC_DELETE_BULK_OVERRIDE ?? "").toLowerCase();
-  return v === "1" || v === "true" || v === "yes";
-}
-
-/**
- * Three buckets returned by computeDeletePlan, exposed so the execution
- * loop can take a different action for each:
- *   - `toDelete`     → issue DeleteObject + drop journal entry.
- *   - `toTombstone`  → no DeleteObject (remote already 404), drop journal
- *                      entry. Lets the journal converge with reality even
- *                      when the remote was cleaned out-of-band.
- *   - `refusedStale` → no DeleteObject, no journal change. Some other
- *                      device modified the remote object since this device
- *                      last synced it; the next pull leg re-pulls via the
- *                      same `hasRemoteChanged` path the conflict detector
- *                      uses. Emitted as `delete-refused-stale-etag` events.
- */
-interface DeletePlan {
-  toDelete: Array<{ key: string; intentVersion: 1 | null }>;
-  toTombstone: string[];
-  refusedStale: Array<{
-    key: string;
-    journalEtag: string;
-    remoteEtag: string;
-    reason: RefusedStaleReason;
-  }>;
-  /**
-   * Populated only when the bulk-asymmetry circuit-breaker tripped. The
-   * caller emits `delete-refused-bulk-asymmetry` as a one-shot summary so
-   * the UI gets one banner-grade signal in addition to the per-key
-   * `delete-refused-stale-etag` events under `refusedStale`.
-   */
-  bulkAsymmetry?: {
-    candidates: number;
-    inScope: number;
-    ratio: number;
-    samplePaths: string[];
-  };
-}
-
-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 isLocallyAbsent(localPath: string): boolean {
-  try {
-    fs.lstatSync(localPath);
-    return false;
-  } catch (err: unknown) {
-    const code =
-      err && typeof err === "object" && "code" in err
-        ? (err as { code?: string }).code
-        : undefined;
-    return code === "ENOENT";
-  }
-}
-
-/**
- * Concurrency cap for the per-file HEAD-O-meter (currency-gated). Sequential
- * HEADs would add ~N×(50-200ms) to a sync — for the 261-mirror real-world
- * case that's 15-50s of latency. 16-way concurrency keeps S3 well within
- * per-prefix burst limits (~3,500 GET/HEAD/sec/prefix is the documented
- * floor) and bounded under the AWS-SDK default agent's max-sockets so we
- * don't compete with the in-flight upload pool.
- */
-const DELETE_PLAN_HEAD_CONCURRENCY = 16;
-
-/**
- * Walk every journal key in `scopeRoots` whose local file is missing from
- * disk and bucket each candidate into the right action per `policy`. Hard
- * filters that drop a candidate entirely (no bucket) — regardless of policy:
- *
- *   1. Its key must match (or sit beneath) one of the `scopeRoots` prefixes.
- *   2. Its local file must be missing from disk (lstat ENOENT). We use
- *      `lstat` (not `existsSync`) so a dangling symlink — a link whose
- *      target has been removed but whose link file is still on disk —
- *      counts as "still present locally" and is NOT delete-propagated.
- *      Pre-fix, existsSync followed the link, returned false, and the
- *      entry was queued for remote DeleteObject in the same sync that
- *      had just uploaded it via `uploadSymlink` — the link round-tripped
- *      as "upload, then delete" in one cycle. ENOENT means truly absent
- *      → eligible; other lstat errors propagate.
- *   3. The current ignore filter (`shouldSync`) accepts the key — paths
- *      filtered out by `.hqignore` / `.gitignore` / `DEFAULT_IGNORES` are
- *      never delete-propagated. Closes the failure mode where a path lives
- *      in the vault (and journal) but the local walk skips it because of
- *      asymmetric ignore rules.
- *
- *      Dual-hint probe: by the time we're considering this entry for
- *      remote deletion, the local file is already gone — we have no way to
- *      know whether it was a regular file or a symlink record. A single
- *      `isDir=false` probe would silently keep the remote record alive
- *      whenever the only matching `.hqinclude` allowlist pattern is dir-
- *      only (e.g. `companies/*\/knowledge/`), since gitignore's slash
- *      semantics reject the slashless probe. The same dual-hint pattern in
- *      `walkDir`/`collectFiles` (push) and `computePullPlan` (pull) applies
- *      symmetrically here. Pure path lookup, no I/O.
- *   4. The key does NOT match `EPHEMERAL_PATH_PATTERN`. Conflict mirrors
- *      are local-only artifacts that should never have been journaled in
- *      the first place; the dedicated reconcile command sweeps already-
- *      journaled mirrors. Excluding them here keeps a regular `sync now`
- *      from accidentally deleting a mirror another device is still
- *      reviewing.
- *
- * Then per-policy bucketing:
- *
- *   - `"currency-gated"` (default, safest): issue a HEAD against the remote.
- *     200 + `normalizeEtag(remote) === entry.remoteEtag` → `toDelete`.
- *     200 + mismatch → `refusedStale` (peer drift; let pull re-pull).
- *     404 → `toTombstone` (remote was cleaned out-of-band).
- *     If the journal entry has no recorded `remoteEtag` (legacy entries
- *     written before etag tracking), the candidate falls back to
- *     `refusedStale` with `reason: "legacy-no-etag"` — we can't prove
- *     currency without an etag, so refusal is the safe direction. The
- *     journal entry survives so a future sync with a recorded etag can
- *     re-evaluate.
- *
- *     HEAD calls are batched at `DELETE_PLAN_HEAD_CONCURRENCY` so a large
- *     candidate set (e.g. a one-shot reconcile sweep) doesn't serialize
- *     into N×RTT latency. The candidate set is materialized into a list
- *     first (synchronous filters above), then the HEAD pass runs in
- *     bounded-parallel chunks.
- *
- *     Note: there is a TOCTOU window between this HEAD and the eventual
- *     `deleteRemoteFile` call in the share() execution loop. If a peer
- *     overwrites the object in that window (~50-200ms), the resulting
- *     delete-marker lands on a newer version than we verified. S3
- *     versioning makes the worst case recoverable (prior versions are
- *     retained), and the conditional-delete primitive does not exist on
- *     S3 DeleteObject — only PutObject/CopyObject accept `IfMatch`. The
- *     window is bounded, not zero. Realtime sync (separate work) reduces
- *     it further by keeping the journal continuously fresh.
- *   - `"owned-only"`: include only entries with `direction === "up"`. No
- *     HEAD round-trip. Goes to `toDelete`. Legacy fallback.
- *   - `"all"`: include every candidate. No HEAD, no direction check. Goes
- *     to `toDelete`. Caller has explicitly opted out of safety gates.
- *
- * Empty `scopeRoots` ⇒ empty plan (caller didn't opt in).
- */
-async function computeDeletePlan(
-  journal: SyncJournal,
-  syncRoot: string,
-  scopeRoots: string[],
-  shouldSync: (filePath: string, isDir?: boolean) => boolean,
-  policy: "currency-gated" | "owned-only" | "all",
-  ctx: EntityContext,
-  // True for a COMPANY-scoped push (personalMode !== true): the sync root is
-  // the company folder and journal keys are bucket-relative, so a literal
-  // `companies/…` key is scope-invalid (see the poisoned-key branch below).
-  // Personal-vault pushes legitimately journal `companies/{slug}/…` keys.
-  companyScoped: boolean = true,
-): Promise<DeletePlan> {
-  const plan: DeletePlan = { toDelete: [], toTombstone: [], refusedStale: [] };
-  if (scopeRoots.length === 0) return plan;
-
-  // Stage 1: synchronous pre-filter. Walk every journal entry and either
-  // drop it (hard filter), assign it directly to a bucket (owned-only /
-  // all), or queue it for HEAD (currency-gated). Keeping this synchronous
-  // means the HEAD pass below sees a single, deduplicated candidate list
-  // and the journal-mutation buckets are already settled before any I/O.
-  type HeadCandidate = { key: string; journalEtag: string; intentVersion: 1 | null };
-  const headCandidates: HeadCandidate[] = [];
-  // Litter drain bucket — kept separate from `plan.toDelete` so the
-  // bulk-asymmetry breaker (which moves toDelete + headCandidates into
-  // `refusedStale` when it trips) can't sweep these out. See
-  // `isVaultLitterArtifact` for the patterns and rationale: by construction
-  // these aren't user content losses, so a high ratio of litter must not
-  // refuse the drain — that's the whole point of the bypass. Merged into
-  // `plan.toDelete` after the breaker check.
-  const litterToDelete: string[] = [];
-  // Bulk-asymmetry tracking: count every in-scope journal entry (denominator)
-  // and every entry that would have been a delete-candidate before the guard
-  // (numerator). The numerator is the WHOLE prospective destructive set:
-  // intent-backed picks (owned-only/all toDelete, currency-gated
-  // headCandidates, legacy-no-etag refusals) AND intent-less disappearances.
-  //
-  // 6.14.19 (#227) narrowed it to intent-less disappearances only, on the
-  // premise that a current watcher intent is affirmative evidence of a
-  // deliberate delete. A wiped, swapped, unmounted or partially-restored tree
-  // observed by a live watcher mints an intent per descendant, so that premise
-  // does not hold and the breaker stopped covering the exact failure mode it
-  // exists for (incident 2026-07-30: 1,108 intent-backed deletions in one
-  // push). Intent currency is a per-file property; the breaker is a whole-set
-  // health check, and the two must not be conflated.
-  //
-  // We do NOT count "ENOENT but ignore-filtered" or "ENOENT but ephemeral" —
-  // those drop out of the plan entirely on their own and don't reflect
-  // mirror-loss intent — nor litter drains (see above), which are intentional
-  // ratchet-cleanup, not mass-delete intent.
-  let inScopeJournalEntries = 0;
-  let bulkCandidatePicks = 0;
-  // Intent-less candidates already parked in `refusedStale`. On a trip they are
-  // re-labelled `bulk-asymmetry` in place rather than refused twice.
-  const intentlessKeys = new Set<string>();
-
-  for (const [relativeKey, entry] of Object.entries(journal.files)) {
-    const inScope = scopeRoots.some(
-      (root) =>
-        root === "" ||
-        relativeKey === root ||
-        relativeKey.startsWith(`${root}/`),
-    );
-    if (!inScope) continue;
-
-    // A tombstoned entry has ALREADY had its disposition decided — by a scope
-    // shrink, `hq sync narrow --apply`, a manual prune, or a pull-side
-    // intentional-delete record. It must never be re-evaluated as a fresh
-    // delete candidate.
-    //
-    // This matters most for `all` -> `shared`: `tombstoneEntry` deliberately
-    // KEEPS `hash`, `direction` and `remoteEtag` (so a recovery flow can see
-    // what was there), and the shrink removes the file locally. Every one of
-    // those entries therefore presents as locally-absent, intent-less and
-    // etag-current — which, now that authorization is etag-only, is an
-    // instruction to delete another member's files out of the shared company
-    // vault, for the crime of having narrowed one's own sync scope.
-    //
-    // Until now the ONLY thing standing in the way was `shouldSync` happening
-    // to carry a `prefixSet` (see `createPushRunContext`); any run that
-    // resolved no prefix set — a degraded scope lookup, a caller that does not
-    // set one — would have walked straight through. That is far too load-
-    // bearing for an implicit dependency, so the invariant is stated here
-    // directly.
-    //
-    // `local-delete` is the ONE reason that must pass: the pull leg stamps it
-    // as a deliberate producer hand-off ("the user removed this; push leg,
-    // finish the job"), and skipping it would strand exactly the deletes this
-    // change exists to enable. Every other reason — scope_shrink,
-    // narrow_apply, manual, or an absent/unrecognised one — means "stop
-    // tracking, do NOT touch the remote", so the test is written fail-closed:
-    // only the explicit hand-off is let through.
-    //
-    // Skipped BEFORE `inScopeJournalEntries++` so these inflate neither the
-    // numerator nor the denominator of the bulk-asymmetry ratio. Excluding
-    // them from the denominator can only make the breaker MORE likely to trip,
-    // which is the safe direction.
-    if (isTombstone(entry) && entry.removedReason !== "local-delete") continue;
-
-    inScopeJournalEntries++;
-    const localPath = localPathForVaultKey(syncRoot, relativeKey);
-
-    // Scope-invalid journal keys (incident 2026-07-11): in a COMPANY-scoped
-    // context, a journal entry at a literal `companies/…` key records a
-    // doubled-tree poisoning upload. HEAD/DeleteObject on such a key via the
-    // presign transport is rejected by the server validator
-    // (INVALID_KEY_COMPANIES_SCOPED) and would error the push, so route it
-    // straight to `toTombstone` (journal drop + local doubled-tree cleanup, no
-    // remote call). Personal-vault pushes (personalMode) carry legitimate
-    // `companies/{slug}/…` keys and are unaffected (companyScoped=false).
-    // Checked before the presentLocally gate: the poison file lives at the
-    // doubled path and must drain even while still on disk.
-    if (companyScoped && relativeKey.startsWith("companies/")) {
-      plan.toTombstone.push(relativeKey);
-      continue;
-    }
-
-    let presentLocally = true;
-    try {
-      fs.lstatSync(localPath);
-    } catch (err: unknown) {
-      if (
-        err &&
-        typeof err === "object" &&
-        "code" in err &&
-        (err as { code?: string }).code === "ENOENT"
-      ) {
-        presentLocally = false;
-      } else {
-        throw err;
-      }
-    }
-    if (presentLocally) continue;
-
-    if (!companyScoped && isPersonalVaultDeletionExcluded(relativeKey)) {
-      continue;
-    }
-
-    // Vault-litter drain (6.0.2): conflict mirrors + rescue drift markers
-    // ALWAYS drain, bypassing `shouldSync` (which would skip them when the
-    // parent path is in personal-vault default exclusions like
-    // `.obsidian/**`), the `isEphemeralPath` skip (which protects FRESH
-    // local conflict mirrors but accidentally also protects existing vault
-    // litter), the policy gate (no meaningful ownership/freshness for
-    // litter), and the bulk-asymmetry breaker (intentional ratchet-drain,
-    // not corrupt-mirror mass-delete intent). See `isVaultLitterArtifact`
-    // for the full rationale and patterns. Queued via the separate
-    // `litterToDelete` bucket so the breaker can't sweep these out.
-    if (isVaultLitterArtifact(relativeKey)) {
-      litterToDelete.push(relativeKey);
-      continue;
-    }
-
-    if (!shouldSync(localPath, false) && !shouldSync(localPath, true)) continue;
-    // Ephemeral artifacts (conflict mirrors) never propagate-delete via the
-    // normal path — see EPHEMERAL_PATH_PATTERN doc. NOTE: this is a no-op
-    // post-litter-drain above — any key matching EPHEMERAL_PATH_PATTERN was
-    // already routed to `litterToDelete`. Retained as defense-in-depth +
-    // documentation of the policy-side intent.
-    if (isEphemeralPath(relativeKey)) continue;
-
-    // Journal-honesty guard: an entry flagged `localDiverges` recorded the
-    // remote etag only to silence a re-fired conflict (#137) — the local copy
-    // NEVER matched that remote. Its currency would falsely "match" on HEAD, so
-    // propagating a delete would destroy the divergent remote version. Refuse it
-    // regardless of policy, and do NOT count it toward the bulk-asymmetry ratio
-    // (it isn't a genuine mirror-loss candidate). Cleared by a real download.
-    if (entry.localDiverges) {
-      plan.refusedStale.push({
-        key: relativeKey,
-        journalEtag: entry.remoteEtag ?? "<divergent-local>",
-        remoteEtag: "<not-checked>",
-        reason: "divergent-local",
-      });
-      continue;
-    }
-
-    if (!hasCurrentLocalDeleteIntent(entry)) {
-      // A delete intent is minted ONLY by a live watcher, at the instant it
-      // observes the unlink. Three of the four ways HQ syncs never construct a
-      // watcher at all — outpost/agent boxes run a one-shot runner, `hq sync
-      // now` is one-shot, and the desktop app drops `--event-push` (and with it
-      // the whole TreeWatcher) whenever Instant-sync is off. On those surfaces
-      // an intent can never exist, so requiring one made deletes structurally
-      // impossible rather than merely gated. Files deleted while no watcher was
-      // running also stranded permanently: the file is already gone, so no
-      // watcher can ever retroactively witness it.
-      //
-      // `currency-gated` therefore authorizes on ETag currency alone. The
-      // per-file question it answers is unchanged — "is the remote object still
-      // exactly what this journal recorded, i.e. has no peer touched it since"
-      // — and a mismatch still refuses (`stale-etag`) so a peer's newer work is
-      // never destroyed.
-      //
-      // The whole-set question ("does my local mirror look catastrophically
-      // empty") is NOT answered by the ETag, and must not be conflated with it:
-      // in the steady state nobody has overwritten anything, so a moved hqRoot,
-      // unmounted volume, fresh clone or partial restore presents mass-ENOENT
-      // with perfectly matching ETags. That is exactly how the 2026-05-25
-      // indigo vault mass-delete destroyed 559 objects. The bulk-asymmetry
-      // breaker below is the guard for that class and is deliberately left
-      // intact — these candidates are counted into `bulkCandidatePicks` on the
-      // SAME line as intent-backed ones, so relaxing the per-file gate cannot
-      // weaken the whole-set one. See policy `sync-delete-bulk-asymmetry-guard`
-      // (hard) and workspace/reports/indigo-vault-mass-delete-debug.md.
-      //
-      // `owned-only` keeps requiring an intent: it is the documented rollback
-      // knob, and an operator who selects it is asking for the stricter path.
-      if (policy === "owned-only") {
-        // Still counted into the breaker exactly as before: an owned-only run
-        // whose mirror has gone missing must trip the whole-set guard even
-        // though each individual key is refused for want of an intent.
-        if (entry.direction === "up") {
-          bulkCandidatePicks++;
-          intentlessKeys.add(relativeKey);
-        }
-        plan.refusedStale.push({
-          key: relativeKey,
-          journalEtag: entry.remoteEtag ?? "<missing-delete-intent>",
-          remoteEtag: "<not-checked>",
-          reason: "missing-delete-intent",
-        });
-        continue;
-      }
-      if (policy === "currency-gated") {
-        bulkCandidatePicks++;
-        intentlessKeys.add(relativeKey);
-        // No etag on record ⇒ nothing to compare ⇒ no authorization. Refused
-        // for the same reason an intent-backed legacy entry is (below).
-        if (!entry.remoteEtag) {
-          plan.refusedStale.push({
-            key: relativeKey,
-            journalEtag: "<legacy-no-etag>",
-            remoteEtag: "<unknown>",
-            reason: "legacy-no-etag",
-          });
-          continue;
-        }
-        headCandidates.push({
-          key: relativeKey,
-          journalEtag: entry.remoteEtag,
-          intentVersion: null,
-        });
-        continue;
-      }
-      // policy === "all" is deliberately NOT relaxed here. It already skips the
-      // bulk-asymmetry breaker, so letting it skip the intent gate too would
-      // make it a wholly unguarded mass delete — a strictly larger blast radius
-      // than this change is scoped to. It keeps refusing intent-less entries
-      // exactly as before.
-      plan.refusedStale.push({
-        key: relativeKey,
-        journalEtag: entry.remoteEtag ?? "<missing-delete-intent>",
-        remoteEtag: "<not-checked>",
-        reason: "missing-delete-intent",
-      });
-      continue;
-    }
-
-    bulkCandidatePicks++;
-    if (policy === "all") {
-      // policy:"all" is the explicit-opt-out emergency-reconcile mode; the
-      // bulk-asymmetry guard skips this branch (caller asserted intent).
-      plan.toDelete.push({
-        key: relativeKey,
-        intentVersion: entry.localDeleteIntent!.version,
-      });
-      continue;
-    }
-    if (policy === "owned-only") {
-      if (entry.direction !== "up") {
-        // Not a delete candidate under owned-only, but it WAS missing
-        // locally. Don't count it for the bulk guard — direction:'down'
-        // entries that vanish locally are silently ignored by this policy
-        // anyway, so they don't represent intent to mass-delete.
-        bulkCandidatePicks--;
-        continue;
-      }
-      plan.toDelete.push({
-        key: relativeKey,
-        intentVersion: entry.localDeleteIntent!.version,
-      });
-      continue;
-    }
-    // currency-gated: queue for HEAD unless the entry is legacy (no etag).
-    const journalEtag = entry.remoteEtag;
-    if (!journalEtag) {
-      plan.refusedStale.push({
-        key: relativeKey,
-        journalEtag: "<legacy-no-etag>",
-        remoteEtag: "<unknown>",
-        reason: "legacy-no-etag",
-      });
-      continue;
-    }
-    headCandidates.push({
-      key: relativeKey,
-      journalEtag,
-      intentVersion: entry.localDeleteIntent!.version,
-    });
-  }
-
-  // Bulk-asymmetry circuit-breaker. See `BULK_ASYMMETRY_*` constants for
-  // rationale + bypass paths. Skipped under policy:"all" (caller asserted
-  // intent) and under `HQ_SYNC_DELETE_BULK_OVERRIDE` (operator rollback knob).
-  if (
-    policy !== "all" &&
-    !isBulkAsymmetryOverride() &&
-    bulkCandidatePicks >= BULK_ASYMMETRY_MIN_ABS &&
-    inScopeJournalEntries > 0 &&
-    bulkCandidatePicks / inScopeJournalEntries >= BULK_ASYMMETRY_RATIO
-  ) {
-    // Move every staged candidate (both already-bucketed toDelete from
-    // owned-only and queued headCandidates from currency-gated) into
-    // refusedStale with reason "bulk-asymmetry", and re-label the intent-less
-    // entries already parked there. Journal is not mutated; no DeleteObject is
-    // issued; the Stage-2 HEAD pass never runs.
-    const samplePaths: string[] = [];
-    const noteSample = (key: string): void => {
-      if (samplePaths.length < BULK_ASYMMETRY_SAMPLE_CAP) samplePaths.push(key);
-    };
-    for (const refused of plan.refusedStale) {
-      if (!intentlessKeys.has(refused.key)) continue;
-      refused.journalEtag = "<bulk-asymmetry>";
-      refused.remoteEtag = "<not-checked>";
-      refused.reason = "bulk-asymmetry";
-      noteSample(refused.key);
-    }
-    const pushRefused = (key: string): void => {
-      plan.refusedStale.push({
-        key,
-        journalEtag: "<bulk-asymmetry>",
-        remoteEtag: "<not-checked>",
-        reason: "bulk-asymmetry",
-      });
-      noteSample(key);
-    };
-    for (const item of plan.toDelete) pushRefused(item.key);
-    for (const c of headCandidates) pushRefused(c.key);
-    // Emptying the delete list is what makes the trip a refusal rather than a
-    // label. #227 dropped this line, so a tripped breaker stopped nothing it
-    // had not already refused for another reason.
-    plan.toDelete = [];
-    plan.bulkAsymmetry = {
-      candidates: bulkCandidatePicks,
-      inScope: inScopeJournalEntries,
-      ratio: bulkCandidatePicks / inScopeJournalEntries,
-      samplePaths,
-    };
-    // Litter still drains even when the breaker trips — see `litterToDelete`
-    // declaration. The breaker protects against corrupt-mirror mass-deletes
-    // of user content; litter cleanup is orthogonal and should never be
-    // refused for the same reason new-litter producer-side exclusions
-    // shouldn't block it.
-    plan.toDelete.push(...litterToDelete.map((key) => ({ key, intentVersion: null })));
-    return plan;
-  }
-
-  // Stage 2: bounded-parallel HEAD pass. Promise.all over chunks of size
-  // `DELETE_PLAN_HEAD_CONCURRENCY` so a large candidate set doesn't
-  // serialize into N round-trips, and so we don't burst past the AWS-SDK
-  // default agent's per-host socket cap. Each result is bucketed
-  // independently — one failed HEAD doesn't poison the others (errors
-  // propagate from the chunk's Promise.all and are surfaced by share()'s
-  // outer try/catch, mirroring the existing pre-share error handling).
-  // Warm the GET presigns the HEAD pass reuses so a large candidate set doesn't
-  // mint one presign per HEAD and trip the presign breaker. Mirrors the
-  // new-files + tombstone HEAD-pass pre-primes.
-  await primeObjectTransport(
-    ctx,
-    "get",
-    headCandidates.map((c) => c.key),
-  );
-  for (let i = 0; i < headCandidates.length; i += DELETE_PLAN_HEAD_CONCURRENCY) {
-    const chunk = headCandidates.slice(i, i + DELETE_PLAN_HEAD_CONCURRENCY);
-    const results = await Promise.all(
-      chunk.map(async (c) => {
-        try {
-          return {
-            candidate: c,
-            remote: await headRemoteFile(ctx, c.key),
-            scopeExcluded: false,
-          };
-        } catch (err) {
-          if (isAccessDenied(err)) {
-            return { candidate: c, remote: null, scopeExcluded: true };
-          }
-          throw err;
-        }
-      }),
-    );
-    for (const { candidate, remote, scopeExcluded } of results) {
-      if (scopeExcluded) {
-        continue;
-      }
-      if (remote === null) {
-        plan.toTombstone.push(candidate.key);
-        continue;
-      }
-      const currentEtag = normalizeEtag(remote.etag);
-      if (currentEtag === candidate.journalEtag) {
-        plan.toDelete.push({
-          key: candidate.key,
-          intentVersion: candidate.intentVersion,
-        });
-      } else {
-        plan.refusedStale.push({
-          key: candidate.key,
-          journalEtag: candidate.journalEtag,
-          remoteEtag: currentEtag,
-          reason: "stale-etag",
-        });
-      }
-    }
-  }
-
-  // Litter drains alongside the normal candidates — bypasses every gate but
-  // settles into the same plan.toDelete bucket so the share() executor's
-  // delete loop tombstones each key identically (DeleteObject + remove from
-  // journal). Merged at the end so the bulk-asymmetry breaker above had its
-  // chance to NOT include litter in either the numerator or the sweep.
-  for (const key of litterToDelete) {
-    plan.toDelete.push({ key, intentVersion: null });
-  }
-
-  return plan;
-}
-
-/**
- * Walk every journal key that matches one of the supplied `prefixes` and
- * return the keys eligible for unconditional remote `DeleteObject`. Unlike
- * `computeDeletePlan` this DOES NOT check whether the local file is missing
- * — the caller has asserted that these keys no longer belong in this
- * bucket regardless of local state (typically a company that was promoted
- * from personal-bucket fallback to its own team bucket).
- *
- * An entry is in the plan only when ALL of the following hold:
- *
- *   1. Its key matches (or sits beneath) one of the `prefixes`. The match
- *      is exact OR `key.startsWith(prefix + "/")` — same semantics as
- *      `computeDeletePlan`'s scope-root check.
- *   2. When `policy === "owned-only"`: the journal entry's `direction`
- *      is `"up"` (this machine previously uploaded the file). Mirrors
- *      `computeDeletePlan`'s safety property — a misconfigured prefix
- *      list can never erase content pulled from elsewhere.
- *   3. The key is NOT already in `alreadyPlanned` (the standard delete
- *      plan), so a single DeleteObject + journal-update pass processes
- *      each key once.
- *
- * Empty `prefixes` ⇒ empty plan (caller didn't opt in).
- */
-function computeDecommissionPlan(
-  journal: SyncJournal,
-  prefixes: string[],
-  policy: "currency-gated" | "owned-only" | "all",
-  alreadyPlanned: ReadonlySet<string>,
-): string[] {
-  if (prefixes.length === 0) return [];
-  // `currency-gated` exists to gate `propagateDeletes` on per-file proof of
-  // currency (HEAD compare). Decommission is unconditional by design — we
-  // don't need a HEAD check to know whether the key belongs here, the
-  // caller has asserted it doesn't. So for the direction-of-origin safety
-  // gate we collapse `currency-gated` to the `owned-only` behavior:
-  // peer-written entries (direction:'down') are skipped. That's the
-  // conservative choice — a peer who wrote into this bucket should
-  // reconcile their own entry, not have us blast it away on their behalf.
-  const requireOwned = policy === "owned-only" || policy === "currency-gated";
-  const out: string[] = [];
-  for (const [relativeKey, entry] of Object.entries(journal.files)) {
-    if (alreadyPlanned.has(relativeKey)) continue;
-    const matches = prefixes.some(
-      (prefix) =>
-        prefix === "" ||
-        relativeKey === prefix ||
-        relativeKey.startsWith(`${prefix}/`),
-    );
-    if (!matches) continue;
-    if (requireOwned && entry.direction !== "up") continue;
-    out.push(relativeKey);
-  }
-  return out;
-}