@indigoai-us/hq-cloud 6.14.8 → 6.14.10

package/src/cli/sync.ts

@@ -26,6 +26,7 @@ import {
   headRemoteFile,
   primeObjectTransport,
   toPosixKey,
+  classifyVaultKey,
 } from "../s3.js";
 import type { DownloadModeWarning, RemoteFile } from "../s3.js";
 import {
@@ -220,7 +221,13 @@ export type SyncProgressEvent =
       path: string;
       journalEtag: string;
       remoteEtag: string;
-      reason: "stale-etag" | "legacy-no-etag" | "bulk-asymmetry" | "divergent-local";
+      reason:
+        | "stale-etag"
+        | "legacy-no-etag"
+        | "bulk-asymmetry"
+        | "divergent-local"
+        | "missing-delete-intent"
+        | "intent-changed";
     }
   | {
       /**
@@ -348,12 +355,10 @@ export type SyncProgressEvent =
     }
   | {
       /**
-       * Emitted by the PULL leg once per remote key skipped because it is
-       * invalid for the vault's scope — today, a `companies/…`-prefixed key in
-       * a company-scoped vault (the server rejects these with
-       * INVALID_KEY_COMPANIES_SCOPED; see hq-pro files-acl validateObjectKey).
-       * Such keys are bucket poisoning from a client with a stale doubled
-       * local tree writing via direct S3 (incident 2026-07-11). Like
+       * Emitted by the PULL leg once per remote key skipped because the server
+       * will never presign it (for example, a `companies/…`-prefixed key in a
+       * company-scoped vault or a key with control characters). Such keys are
+       * bucket poisoning from an outdated direct-S3 client. Like
        * `skip-size-limit`, this is deliberately NOT `type: "error"` — one bad
        * object must never error a whole company sync (erroring gated
        * heartbeat toolset refreshes fleet-wide in the incident). Surfaced for
@@ -363,6 +368,8 @@ export type SyncProgressEvent =
        */
       type: "skip-invalid-scoped-key";
       path: string;
+      /** Server-compatible invalid-key code, such as INVALID_KEY_CONTROL_CHARS. */
+      errorCode?: string;
     };
 
 export interface SyncOptions {
@@ -816,7 +823,7 @@ async function syncWithOperationLockHeld(
   const plan = planPull(run);
 
   emitPullPlan(run.emit, plan);
-  reportInvalidScopedKeys(run, plan);
+  reportInvalidRemoteKeys(run, plan);
 
   const scopePlan = planScopeShrink(run);
   const scopeRun = executeScopeShrink(run, scopePlan);
@@ -951,30 +958,30 @@ function emitPullPlan(emit: SyncEventEmitter, plan: PullPlan): void {
 }
 
 /**
- * Surface scope-invalid remote keys the planner skipped (see the
- * `invalidScopedKeys` doc on PullPlan). One warning event per key on the
+ * Surface permanently-unpresignable remote keys the planner skipped (see the
+ * `invalidRemoteKeys` doc on PullPlan). One warning event per key on the
  * existing sync event channel (deliberately NOT `type: "error"` — see the
  * `skip-invalid-scoped-key` event doc), plus one best-effort cloud telemetry
  * event on the channel sync already uses (emitCloudTelemetry). Per policy
  * hq-alert-baseline-calibration the documented healthy baseline is ZERO
- * INVALID_KEY_COMPANIES_SCOPED occurrences fleet-wide, so consumers can alert
- * on any non-zero count with no threshold tuning.
+ * invalid-key occurrences fleet-wide, so consumers can alert on any non-zero
+ * count with no threshold tuning.
  */
-function reportInvalidScopedKeys(run: PullRunContext, plan: PullPlan): void {
-  if (plan.invalidScopedKeys.length === 0) return;
-  for (const key of plan.invalidScopedKeys) {
-    run.emit({ type: "skip-invalid-scoped-key", path: key });
+function reportInvalidRemoteKeys(run: PullRunContext, plan: PullPlan): void {
+  if (plan.invalidRemoteKeys.length === 0) return;
+  const countsByErrorCode = new Map<string, number>();
+  for (const { path, errorCode } of plan.invalidRemoteKeys) {
+    run.emit({ type: "skip-invalid-scoped-key", path, errorCode });
+    countsByErrorCode.set(errorCode, (countsByErrorCode.get(errorCode) ?? 0) + 1);
+  }
+  for (const [errorCode, count] of countsByErrorCode) {
+    void emitCloudTelemetry(new VaultClient(run.vaultConfig), {
+      eventName: "sync_invalid_scoped_key_skipped",
+      source: "hq-sync",
+      companyUid: run.ctx.uid,
+      properties: { count, errorCode, leg: "pull" },
+    }, { claims: run.options.telemetryClaims });
   }
-  void emitCloudTelemetry(new VaultClient(run.vaultConfig), {
-    eventName: "sync_invalid_scoped_key_skipped",
-    source: "hq-sync",
-    companyUid: run.ctx.uid,
-    properties: {
-      count: plan.invalidScopedKeys.length,
-      errorCode: "INVALID_KEY_COMPANIES_SCOPED",
-      leg: "pull",
-    },
-  }, { claims: run.options.telemetryClaims });
 }
 
 /**
@@ -1201,11 +1208,19 @@ function executeFileTombstoneDelete(
   counters: PullCounters,
 ): void {
   const tombstoneKey = item.remoteFile.key;
-  const tombstonePath = resolveContainedVaultPath(run.companyRoot, tombstoneKey);
-  if (tombstonePath === null) return;
+  const tombstonePath = item.localPath;
+  if (!isDownloadWritePathStillContained(run.companyRoot, tombstoneKey, tombstonePath)) {
+    run.emit({
+      type: "error",
+      path: tombstoneKey,
+      message: "tombstone-suppress unlink skipped: local parent escaped the sync root",
+    });
+    return;
+  }
   try {
     const lstat = fs.lstatSync(tombstonePath);
-    if (tombstoneTargetDiverged(run.journal, tombstoneKey, tombstonePath, lstat)) {
+    if (!matchesLocalSnapshot(tombstonePath, item.localSnapshot)) {
+      reportLocalSnapshotConflict(run, counters, tombstoneKey);
       return;
     }
     if (lstat.isSymbolicLink() || lstat.isFile()) {
@@ -1251,7 +1266,13 @@ async function executeConflictItem(
   // the `.conflict-` mirror loop AND the journal false-stamp (remote etag over
   // divergent local content) that the keep path produced for these files.
   if (isCloudAuthoritative(vaultKeyForLocalPath(run.hqRoot, localPath))) {
-    downloadItems.push({ action: "download", remoteFile, localPath, isNew: false });
+    downloadItems.push({
+      action: "download",
+      remoteFile,
+      localPath,
+      isNew: false,
+      localSnapshot: item.localSnapshot,
+    });
     run.emit({ type: "reconciled", path: remoteFile.key, direction: "pull" });
     return null;
   }
@@ -1314,6 +1335,7 @@ async function executeConflictItem(
       "down",
       remoteFile.etag,
       item.localMtime.getTime(),
+      item.localSnapshot.kind === "symlink" ? "symlink" : "file",
     );
     run.emit({ type: "reconciled", path: remoteFile.key, direction: "pull" });
     counters.filesSkipped++;
@@ -1403,6 +1425,7 @@ async function executeConflictItem(
       "down",
       remoteFile.etag,
       item.localMtime.getTime(),
+      item.localSnapshot.kind === "symlink" ? "symlink" : "file",
     );
     // Journal-honesty: we recorded the remote etag so this conflict can't
     // re-fire (#137), but the KEPT local copy diverges from that remote — it
@@ -1420,6 +1443,7 @@ async function executeConflictItem(
     remoteFile,
     localPath,
     isNew: false,
+    localSnapshot: item.localSnapshot,
   });
   return null;
 }
@@ -1493,6 +1517,13 @@ async function downloadOne(
       run.ctx,
       remoteFile.key,
       localPath,
+      {
+        beforeReplace: () => {
+          if (!matchesLocalSnapshot(localPath, downloadItem.localSnapshot)) {
+            throw new LocalSnapshotChangedError(remoteFile.key);
+          }
+        },
+      },
     );
     reportModeWarnings(run, modeWarnings);
     const author = metadata?.["created-by"] ?? null;
@@ -1514,6 +1545,7 @@ async function downloadOne(
       remoteFile.etag,
       localLstat.mtimeMs,
       createdBySub,
+      isLocalSymlink ? "symlink" : "file",
     );
 
     const priorEntry = getEntry(run.journal, remoteFile.key);
@@ -1530,7 +1562,9 @@ async function downloadOne(
     counters.bytesDownloaded += size;
     counters.changedPaths.push(remoteFile.key);
   } catch (err) {
-    if (isAccessDenied(err)) {
+    if (err instanceof LocalSnapshotChangedError) {
+      reportLocalSnapshotConflict(run, counters, remoteFile.key);
+    } else if (isAccessDenied(err)) {
       counters.filesSkipped++;
     } else {
       run.emit({
@@ -1621,13 +1655,13 @@ async function verifyPlannedJournalTombstones(
   // never legitimately exist in a company vault, so treating it as verified
   // is safe: the executor cleans the local copy + journal entry instead of
   // the push leg ever re-uploading it (tombstone-not-reupload).
-  const autoVerified: string[] = [];
-  const toHeadVerify: string[] = [];
-  for (const key of plan.tombstones) {
-    if (run.options.personalMode !== true && key.startsWith("companies/")) {
-      autoVerified.push(key);
+  const autoVerified: PullPlan["tombstones"] = [];
+  const toHeadVerify: PullPlan["tombstones"] = [];
+  for (const tombstone of plan.tombstones) {
+    if (run.options.personalMode !== true && tombstone.key.startsWith("companies/")) {
+      autoVerified.push(tombstone);
     } else {
-      toHeadVerify.push(key);
+      toHeadVerify.push(tombstone);
     }
   }
   plan.tombstones = toHeadVerify;
@@ -1636,22 +1670,22 @@ async function verifyPlannedJournalTombstones(
     return;
   }
 
-  await primeObjectTransport(run.ctx, "get", plan.tombstones);
+  await primeObjectTransport(run.ctx, "get", plan.tombstones.map((t) => t.key));
 
   const HEAD_VERIFY_CONCURRENCY = 5;
-  const verified: string[] = [];
+  const verified: PullPlan["tombstones"] = [];
   for (let i = 0; i < plan.tombstones.length; i += HEAD_VERIFY_CONCURRENCY) {
     const batch = plan.tombstones.slice(i, i + HEAD_VERIFY_CONCURRENCY);
     const results = await Promise.all(
-      batch.map(async (key) => {
+      batch.map(async (tombstone) => {
         try {
-          const head = await headRemoteFile(run.ctx, key);
-          return head === null ? key : null;
+          const head = await headRemoteFile(run.ctx, tombstone.key);
+          return head === null ? tombstone : null;
         } catch (err) {
           if (isAccessDenied(err)) return null;
           run.emit({
             type: "error",
-            path: key,
+            path: tombstone.key,
             message: `tombstone HEAD verify failed (deferring): ${
               err instanceof Error ? err.message : String(err)
             }`,
@@ -1660,8 +1694,8 @@ async function verifyPlannedJournalTombstones(
         }
       }),
     );
-    for (const k of results) {
-      if (k !== null) verified.push(k);
+    for (const tombstone of results) {
+      if (tombstone !== null) verified.push(tombstone);
     }
   }
   plan.tombstones = [...autoVerified, ...verified];
@@ -1672,13 +1706,21 @@ function executeJournalTombstoneDeletes(
   plan: PullPlan,
   counters: PullCounters,
 ): void {
-  for (const key of plan.tombstones) {
-    const localPath = resolveContainedVaultPath(run.companyRoot, key);
-    if (localPath === null) continue;
+  for (const tombstone of plan.tombstones) {
+    const { key, localPath, localSnapshot } = tombstone;
+    if (!isDownloadWritePathStillContained(run.companyRoot, key, localPath)) {
+      run.emit({
+        type: "error",
+        path: key,
+        message: "tombstone unlink skipped: local parent escaped the sync root",
+      });
+      continue;
+    }
     let removedSomething = false;
     try {
       const lstat = fs.lstatSync(localPath);
-      if (tombstoneTargetDiverged(run.journal, key, localPath, lstat)) {
+      if (!matchesLocalSnapshot(localPath, localSnapshot)) {
+        reportLocalSnapshotConflict(run, counters, key);
         continue;
       }
       if (lstat.isSymbolicLink() || lstat.isFile()) {
@@ -1879,29 +1921,64 @@ function isDownloadWritePathStillContained(
   return resolved !== null && path.resolve(resolved) === path.resolve(localPath);
 }
 
-function tombstoneTargetDiverged(
-  journal: SyncJournal,
-  key: string,
-  localPath: string,
-  lstat: fs.Stats,
-): boolean {
-  const journalEntry = journal.files[key];
-  if (!journalEntry?.hash) {
-    return lstat.isSymbolicLink() || lstat.isFile();
-  }
-
+function snapshotLocalState(localPath: string): LocalSnapshot | null {
   try {
+    const lstat = fs.lstatSync(localPath);
     if (lstat.isSymbolicLink()) {
-      return hashSymlinkTarget(fs.readlinkSync(localPath)) !== journalEntry.hash;
+      return { kind: "symlink", hash: hashSymlinkTarget(fs.readlinkSync(localPath)) };
     }
     if (lstat.isFile()) {
-      return hashFile(localPath) !== journalEntry.hash;
+      return { kind: "file", hash: hashFile(localPath) };
     }
-  } catch {
-    return true;
+    if (lstat.isDirectory()) return { kind: "directory" };
+    return { kind: "other" };
+  } catch (err: unknown) {
+    const code =
+      err && typeof err === "object" && "code" in err
+        ? (err as { code?: string }).code
+        : undefined;
+    return code === "ENOENT" ? { kind: "absent" } : null;
   }
+}
+
+function matchesLocalSnapshot(localPath: string, expected: LocalSnapshot): boolean {
+  const actual = snapshotLocalState(localPath);
+  if (actual === null || actual.kind !== expected.kind) return false;
+  return (
+    (actual.kind !== "file" && actual.kind !== "symlink") ||
+    actual.hash === (expected as Extract<LocalSnapshot, { hash: string }>).hash
+  );
+}
 
-  return false;
+function hasCurrentLocalDeleteIntent(
+  entry: SyncJournal["files"][string] | undefined,
+): boolean {
+  const intent = entry?.localDeleteIntent;
+  return !!(
+    intent &&
+    intent.version === 1 &&
+    entry.remoteEtag &&
+    entry.kind &&
+    intent.remoteEtag === entry.remoteEtag &&
+    intent.localHash === entry.hash &&
+    intent.localKind === entry.kind
+  );
+}
+
+function reportLocalSnapshotConflict(
+  run: PullRunContext,
+  counters: PullCounters,
+  key: string,
+): void {
+  counters.conflicts++;
+  counters.conflictPaths.push(key);
+  run.emit({ type: "conflict", path: key, direction: "pull", resolution: "skip" });
+}
+
+class LocalSnapshotChangedError extends Error {
+  constructor(key: string) {
+    super(`local state changed while downloading ${key}; replanning required`);
+  }
 }
 
 /**
@@ -1910,8 +1987,18 @@ function tombstoneTargetDiverged(
  * decide what to do. `localHash` is carried on `conflict` items so the
  * executor can hand it to `resolveConflict` without re-hashing.
  */
+type LocalSnapshot =
+  | { kind: "absent" | "directory" | "other" }
+  | { kind: "file" | "symlink"; hash: string };
+
 type PullPlanItem =
-  | { action: "download"; remoteFile: RemoteFile; localPath: string; isNew: boolean }
+  | {
+      action: "download";
+      remoteFile: RemoteFile;
+      localPath: string;
+      isNew: boolean;
+      localSnapshot: LocalSnapshot;
+    }
   | { action: "skip-ignored"; remoteFile: RemoteFile; localPath: string }
   | { action: "skip-personal-mode"; remoteFile: RemoteFile; localPath: string }
   | { action: "skip-unchanged"; remoteFile: RemoteFile; localPath: string }
@@ -1940,7 +2027,12 @@ type PullPlanItem =
   // (keys ABSENT from the LIST, HEAD-verified before delete), these are
   // suppressed purely on the FILE_TOMBSTONE authority and skip HEAD-verify (the
   // remote object is present by definition).
-  | { action: "tombstone-delete"; remoteFile: RemoteFile; localPath: string }
+  | {
+      action: "tombstone-delete";
+      remoteFile: RemoteFile;
+      localPath: string;
+      localSnapshot: LocalSnapshot;
+    }
   | {
       action: "conflict";
       remoteFile: RemoteFile;
@@ -1962,6 +2054,7 @@ type PullPlanItem =
       // and silently fail to stamp the journal — leaving the
       // conflict to re-fire forever.
       localSize: number;
+      localSnapshot: LocalSnapshot;
     };
 
 interface PullPlan {
@@ -1983,7 +2076,11 @@ interface PullPlan {
    * propagating the peer's push-side delete cross-machine (Bug #9).
    * Carried on the plan so the executor can iterate without re-walking.
    */
-  tombstones: string[];
+  tombstones: Array<{
+    key: string;
+    localPath: string;
+    localSnapshot: LocalSnapshot;
+  }>;
   /**
    * Count of `tombstone-delete` items — remote keys present in the LIST but
    * suppressed by a FILE_TOMBSTONE (delete-resync). Surfaced on the plan event's
@@ -1991,14 +2088,13 @@ interface PullPlan {
    */
   filesToTombstoneDelete: number;
   /**
-   * Remote keys skipped because they are invalid for the vault's scope
-   * (company mode only: literal `companies/…` keys — bucket poisoning from a
-   * doubled-tree client via direct S3). Counted in `filesExcludedByPolicy`;
-   * carried by key so the caller can log one warning per key and emit
-   * telemetry. Healthy baseline is an empty array (policy
+   * Remote keys skipped because the server will never presign them. Counted in
+   * `filesExcludedByPolicy`; carried with the server-compatible error code so
+   * the caller can log one warning per key and emit telemetry. Healthy
+   * baseline is an empty array (policy
    * hq-alert-baseline-calibration: zero expected, any occurrence is signal).
    */
-  invalidScopedKeys: string[];
+  invalidRemoteKeys: Array<{ path: string; errorCode: string }>;
 }
 
 /**
@@ -2075,9 +2171,9 @@ function computePullPlan(
   excludePrefixes: readonly ScopePrefixInput[] = [],
 ): PullPlan {
   const items: PullPlanItem[] = [];
-  // Company-mode remote keys invalid for the vault's scope (`companies/…` in a
-  // company bucket) — collected so the caller can warn + emit telemetry.
-  const invalidScopedKeys: string[] = [];
+  // Remote keys the server will never presign — collected so the caller can
+  // warn + emit telemetry without allowing one poison object to fail a pull.
+  const invalidRemoteKeys: Array<{ path: string; errorCode: string }> = [];
   // Clean/current/non-divergent files missing locally — collected here, then
   // resolved post-loop by the bulk-asymmetry decision (tombstone vs. restore).
   const intentionalDeleteCandidates: Array<{
@@ -2086,6 +2182,23 @@ function computePullPlan(
   }> = [];
 
   for (const remoteFile of remoteFiles) {
+    const invalidKey = classifyVaultKey(
+      remoteFile.key,
+      personalMode ? "personal" : "company",
+    );
+    if (invalidKey !== null) {
+      invalidRemoteKeys.push({
+        path: remoteFile.key,
+        errorCode: invalidKey.code,
+      });
+      items.push({
+        action: "skip-excluded-policy",
+        remoteFile,
+        localPath: companyRoot,
+      });
+      continue;
+    }
+
     const localPath = resolveContainedVaultPath(companyRoot, remoteFile.key);
     if (localPath === null) {
       items.push({ action: "skip-excluded-policy", remoteFile, localPath: companyRoot });
@@ -2103,23 +2216,6 @@ function computePullPlan(
       continue;
     }
 
-    // Scope-invalid key filter (incident 2026-07-11). A company vault bucket
-    // is already company-scoped, so a literal `companies/…` key can only be
-    // bucket poisoning — a client with a stale doubled local tree
-    // (companies/{slug}/companies/{slug}/…) pushing via the direct-S3 STS
-    // transport, which bypasses the server validator. The presign download
-    // API rejects these keys (INVALID_KEY_COMPANIES_SCOPED), so attempting to
-    // download them errors the WHOLE company sync. Skip them here — one bad
-    // object must never take down a company sync — and record them on the
-    // plan so the caller can warn + emit telemetry (baseline is zero; any
-    // occurrence is signal). Mirrors the personalMode/malformed-key filters
-    // above. Upload-side counterpart: validateVaultUploadKey in s3.ts.
-    if (!personalMode && remoteFile.key.startsWith("companies/")) {
-      invalidScopedKeys.push(remoteFile.key);
-      items.push({ action: "skip-excluded-policy", remoteFile, localPath });
-      continue;
-    }
-
     if (
       personalMode &&
       remoteFile.key.startsWith("companies/") &&
@@ -2221,6 +2317,7 @@ function computePullPlan(
     const localTombstoneSuppresses =
       journalEntry !== undefined &&
       isTombstone(journalEntry) &&
+      hasCurrentLocalDeleteIntent(journalEntry) &&
       journalEntry.removedAt !== undefined &&
       !isRemoteRecreateAfterTombstone(remoteFile, {
         deletedAt: journalEntry.removedAt,
@@ -2239,6 +2336,7 @@ function computePullPlan(
     //      dangling link on every run.
     //   3. A regular file: indistinguishable from current behaviour.
     let localLstat: fs.Stats | null = null;
+    let plannedLocalSnapshot: LocalSnapshot = { kind: "absent" };
     let localPathBlockedByFileAncestor = false;
     try {
       localLstat = fs.lstatSync(localPath);
@@ -2345,6 +2443,10 @@ function computePullPlan(
           : hashFile(localPath);
       }
       const localChanged = !!journalEntry && journalEntry.hash !== localHash;
+      plannedLocalSnapshot = {
+        kind: isLocalSymlink ? "symlink" : "file",
+        hash: localHash,
+      };
       const remoteChanged =
         !!journalEntry && hasRemoteChanged(remoteFile, journalEntry);
 
@@ -2367,9 +2469,15 @@ function computePullPlan(
             localHash,
             localMtime: localLstat!.mtime,
             localSize: isLocalSymlink ? 0 : localLstat!.size,
+            localSnapshot: plannedLocalSnapshot,
           });
         } else {
-          items.push({ action: "tombstone-delete", remoteFile, localPath });
+          items.push({
+            action: "tombstone-delete",
+            remoteFile,
+            localPath,
+            localSnapshot: plannedLocalSnapshot,
+          });
         }
         continue;
       }
@@ -2395,6 +2503,7 @@ function computePullPlan(
           // every sync.
           localMtime: localLstat!.mtime,
           localSize: isLocalSymlink ? 0 : localLstat!.size,
+          localSnapshot: plannedLocalSnapshot,
         });
         continue;
       }
@@ -2454,6 +2563,7 @@ function computePullPlan(
             localHash,
             localMtime: localLstat!.mtime,
             localSize: localLstat!.size,
+            localSnapshot: plannedLocalSnapshot,
           });
           continue;
         }
@@ -2483,7 +2593,12 @@ function computePullPlan(
       if (journalEntry?.removedReason === "local-delete") {
         continue;
       }
-      items.push({ action: "tombstone-delete", remoteFile, localPath });
+      items.push({
+        action: "tombstone-delete",
+        remoteFile,
+        localPath,
+        localSnapshot: plannedLocalSnapshot,
+      });
       continue;
     }
 
@@ -2496,15 +2611,20 @@ function computePullPlan(
       !localExists &&
       journalEntry !== undefined &&
       !isTombstone(journalEntry) &&
-      !journalEntry.localDiverges &&
-      journalEntry.remoteEtag !== undefined &&
+      hasCurrentLocalDeleteIntent(journalEntry) &&
       normalizeEtag(remoteFile.etag) === journalEntry.remoteEtag
     ) {
       intentionalDeleteCandidates.push({ remoteFile, localPath });
       continue;
     }
 
-    items.push({ action: "download", remoteFile, localPath, isNew: !localExists });
+    items.push({
+      action: "download",
+      remoteFile,
+      localPath,
+      isNew: !localExists,
+      localSnapshot: plannedLocalSnapshot,
+    });
   }
 
   // ── Intentional-delete bulk-asymmetry decision (pull-leg producer) ─────────
@@ -2526,6 +2646,7 @@ function computePullPlan(
         remoteFile: cand.remoteFile,
         localPath: cand.localPath,
         isNew: true,
+        localSnapshot: { kind: "absent" },
       });
     } else {
       tombstoneEntry(journal, cand.remoteFile.key, "local-delete");
@@ -2585,7 +2706,7 @@ function computePullPlan(
   // `propagateDeletes` plan in share.ts.
   const remoteKeySet = new Set<string>();
   for (const rf of remoteFiles) remoteKeySet.add(rf.key);
-  const tombstones: string[] = [];
+  const tombstones: PullPlan["tombstones"] = [];
   for (const key of Object.keys(journal.files)) {
     // Compare membership in POSIX space. A pre-5.47.2 Windows journal key can
     // carry backslash separators; the remote LIST is always forward-slash, so a
@@ -2665,7 +2786,9 @@ function computePullPlan(
       // we can't read local state, so we can't safely decide.
       if (code !== "ENOENT") continue;
     }
-    tombstones.push(key);
+    const localSnapshot = snapshotLocalState(localPath);
+    if (localSnapshot === null) continue;
+    tombstones.push({ key, localPath, localSnapshot });
   }
 
   return {
@@ -2680,7 +2803,7 @@ function computePullPlan(
     filesOutOfScope,
     filesToTombstoneDelete,
     tombstones,
-    invalidScopedKeys,
+    invalidRemoteKeys,
   };
 }
 
@@ -2765,7 +2888,7 @@ function defaultConsoleLogger(event: SyncProgressEvent): void {
     );
   } else if (event.type === "skip-invalid-scoped-key") {
     console.warn(
-      `  ! ${event.path} skipped — invalid 'companies/'-prefixed key in a company-scoped vault (bucket poisoning; INVALID_KEY_COMPANIES_SCOPED)`,
+      `  ! ${event.path} skipped — invalid vault key (${event.errorCode ?? "INVALID_KEY_COMPANIES_SCOPED"})`,
     );
   }
 }

package/src/journal.ts

@@ -425,6 +425,7 @@ export function updateEntry(
   remoteEtag?: string,
   mtimeMs?: number,
   createdBySub?: string,
+  kind?: "file" | "symlink",
 ): void {
   const entry: JournalEntry = {
     hash,
@@ -444,6 +445,9 @@ export function updateEntry(
   if (createdBySub !== undefined && createdBySub !== "") {
     entry.createdBySub = createdBySub;
   }
+  if (kind !== undefined) {
+    entry.kind = kind;
+  }
   journal.files[relativePath] = entry;
   journal.lastSync = new Date().toISOString();
 }
@@ -593,6 +597,30 @@ export function tombstoneEntry(
   entry.removedReason = reason;
 }
 
+/**
+ * Mark a journal entry for a user-authorized local delete. Callers must
+ * capture the local hash and kind before removing the object; an absent path
+ * alone is never deletion intent.
+ */
+export function markLocalDeleteIntent(
+  journal: SyncJournal,
+  relativePath: string,
+  localHash: string,
+  localKind: "file" | "symlink",
+): boolean {
+  const entry = journal.files[relativePath];
+  if (!entry?.remoteEtag || entry.hash !== localHash || entry.kind !== localKind) {
+    return false;
+  }
+  entry.localDeleteIntent = {
+    version: 1,
+    remoteEtag: entry.remoteEtag,
+    localHash,
+    localKind,
+  };
+  return true;
+}
+
 /** True if the entry is a tombstone (set by `tombstoneEntry`). */
 export function isTombstone(entry: JournalEntry | undefined): boolean {
   return !!entry && typeof entry.removedAt === "string";