@indigoai-us/hq-cloud 6.14.9 → 6.14.10

package/src/cli/sync.ts

@@ -221,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";
     }
   | {
       /**
@@ -1202,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()) {
@@ -1252,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;
   }
@@ -1315,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++;
@@ -1404,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
@@ -1421,6 +1443,7 @@ async function executeConflictItem(
     remoteFile,
     localPath,
     isNew: false,
+    localSnapshot: item.localSnapshot,
   });
   return null;
 }
@@ -1494,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;
@@ -1515,6 +1545,7 @@ async function downloadOne(
       remoteFile.etag,
       localLstat.mtimeMs,
       createdBySub,
+      isLocalSymlink ? "symlink" : "file",
     );
 
     const priorEntry = getEntry(run.journal, remoteFile.key);
@@ -1531,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({
@@ -1622,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;
@@ -1637,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)
             }`,
@@ -1661,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];
@@ -1673,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()) {
@@ -1880,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
+  );
+}
+
+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" });
+}
 
-  return false;
+class LocalSnapshotChangedError extends Error {
+  constructor(key: string) {
+    super(`local state changed while downloading ${key}; replanning required`);
+  }
 }
 
 /**
@@ -1911,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 }
@@ -1941,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;
@@ -1963,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 {
@@ -1984,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
@@ -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 {

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";

package/src/personal-vault.ts

@@ -105,6 +105,21 @@ export interface PersonalVaultOptions {
  */
 export const PERSONAL_VAULT_MANIFEST_KEY = "companies/manifest.yaml";
 
+/**
+ * Release-owned scaffold and reindex-generated wrappers must never be
+ * delete-propagated from the personal vault. They are recreated locally by a
+ * release or `hq reindex`, so an ordinary local absence is not user intent.
+ */
+export function isPersonalVaultDeletionExcluded(key: string): boolean {
+  const normalized = key.split("\\").join("/").replace(/^\.\//, "");
+  return (
+    normalized === "core" ||
+    normalized.startsWith("core/") ||
+    normalized === ".claude/skills" ||
+    normalized.startsWith(".claude/skills/")
+  );
+}
+
 export function computePersonalVaultPaths(
   hqRoot: string,
   opts: PersonalVaultOptions = {},

package/src/s3.ts

@@ -809,6 +809,7 @@ export async function downloadFile(
   ctx: EntityContext,
   key: string,
   localPath: string,
+  options: { beforeReplace?: () => void } = {},
 ): Promise<{
   metadata?: Record<string, string>;
   contentHash?: string;
@@ -902,6 +903,7 @@ export async function downloadFile(
     const tempPath = downloadTempPath(localPath);
     try {
       fs.symlinkSync(symlinkTarget, tempPath);
+      options.beforeReplace?.();
       fs.renameSync(tempPath, localPath);
     } catch (err) {
       removeTempPath(tempPath);
@@ -1011,6 +1013,7 @@ export async function downloadFile(
       }
     }
 
+    options.beforeReplace?.();
     fs.renameSync(tempPath, localPath);
     tempReady = false;
   } finally {

package/src/types.ts

@@ -26,6 +26,8 @@ export interface JournalEntry {
   size: number;
   syncedAt: string;
   direction: "up" | "down";
+  /** Kind of local object represented by this entry. */
+  kind?: "file" | "symlink";
   /**
    * Cognito `sub` of the file's author, captured from the object's
    * `created-by-sub` S3 user-metadata at download time (zero extra network —
@@ -72,6 +74,17 @@ export interface JournalEntry {
    */
   removedAt?: string;
   removedReason?: "scope_shrink" | "narrow_apply" | "manual" | "local-delete";
+  /**
+   * Explicit local-delete intent. Unlike the legacy `removedReason` marker,
+   * this is bound to the exact synced remote revision and local object shape
+   * that the user approved for deletion.
+   */
+  localDeleteIntent?: {
+    version: 1;
+    remoteEtag: string;
+    localHash: string;
+    localKind: "file" | "symlink";
+  };
   /**
    * Durable automatic-pull retention marker. Set when a scope shrink keeps an
    * out-of-scope caller-authored or unknown-author entry on disk instead of