@indigoai-us/hq-cloud 6.12.4 → 6.13.0

package/src/cli/sync.test.ts

@@ -279,6 +279,76 @@ describe("sync", () => {
     expect(fs.readFileSync(path.join(companyDocs, "handoff.md"), "utf-8")).toBe("local version");
   });
 
+  it("conflict keep marks the entry localDiverges (journal-honesty: kept copy never matched the recorded remote etag)", async () => {
+    const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
+    fs.mkdirSync(companyDocs, { recursive: true });
+    fs.writeFileSync(path.join(companyDocs, "handoff.md"), "local version");
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "docs/handoff.md": {
+            hash: "old-hash-from-last-sync",
+            size: 20,
+            syncedAt: new Date(Date.now() - 3600000).toISOString(),
+            direction: "down",
+          },
+        },
+      }),
+    );
+
+    const result = await sync({
+      company: "acme",
+      onConflict: "keep",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+
+    expect(result.conflicts).toBe(1);
+    const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+    // remoteEtag still recorded so the conflict can't re-fire (#137 invariant)…
+    expect(journal.files["docs/handoff.md"].remoteEtag).toBeTruthy();
+    // …but the kept-local copy is flagged divergent so a later currency-gated
+    // delete cannot fire on a journal that lies about local==remote.
+    expect(journal.files["docs/handoff.md"].localDiverges).toBe(true);
+  });
+
+  it("a genuine download clears a stale localDiverges flag (entry is now truly local==remote)", async () => {
+    const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
+    fs.mkdirSync(companyDocs, { recursive: true });
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "2",
+        lastSync: new Date().toISOString(),
+        files: {
+          "docs/handoff.md": {
+            hash: "old-divergent-hash",
+            size: 20,
+            syncedAt: new Date(Date.now() - 3600000).toISOString(),
+            direction: "down",
+            remoteEtag: "old-etag",
+            localDiverges: true,
+          },
+        },
+        pulls: [],
+      }),
+    );
+    // Remote advanced to a new etag; local absent → genuine download lands the
+    // remote bytes, so local==remote now and the divergence flag must clear.
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: "docs/handoff.md", size: 42, lastModified: new Date(), etag: '"new-etag"' },
+    ]);
+
+    await sync({ company: "acme", vaultConfig: mockConfig, hqRoot: tmpDir });
+
+    expect(fs.existsSync(path.join(companyDocs, "handoff.md"))).toBe(true);
+    const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+    expect(journal.files["docs/handoff.md"]?.localDiverges).toBeFalsy();
+  });
+
   it("emits a conflict event with path + resolution on hash mismatch", async () => {
     const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
     fs.mkdirSync(companyDocs, { recursive: true });
@@ -451,6 +521,58 @@ describe("sync", () => {
     expect(litter).toHaveLength(1);
   });
 
+  it("cloud-authoritative file is PULL-WINS on conflict: overwrites local, no mirror, no false-stamp", async () => {
+    // company-brief.md is server-regenerated (gardener), so a divergence is not
+    // a real conflict — the cloud copy wins. Even under --on-conflict keep, the
+    // conflict path must short-circuit to a plain overwrite: NO `.conflict-`
+    // mirror (the loop) and NO journal stamp of the remote etag over divergent
+    // local content (Finding B). Contrast the docs/handoff.md test above, which
+    // (correctly) keeps local + mirrors for a client-owned file.
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    fs.writeFileSync(path.join(companyRoot, "company-brief.md"), "local richer brief");
+
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: "company-brief.md", size: 17, lastModified: new Date(), etag: '"newbrief"' },
+    ]);
+    // Default downloadFile mock writes "mock file content" — the cloud copy.
+
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "company-brief.md": {
+            hash: "stale-hash",
+            size: 18,
+            syncedAt: new Date(Date.now() - 3600000).toISOString(),
+            direction: "down",
+          },
+        },
+      }),
+    );
+
+    const result = await sync({
+      company: "acme",
+      onConflict: "keep",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+
+    // Cloud wins: not counted as a conflict; local overwritten with the cloud copy.
+    expect(result.conflicts).toBe(0);
+    expect(result.conflictPaths).toEqual([]);
+    expect(
+      fs.readFileSync(path.join(companyRoot, "company-brief.md"), "utf-8"),
+    ).toBe("mock file content");
+    // No conflict mirror littered.
+    const litter = fs
+      .readdirSync(companyRoot)
+      .filter((f) => f.includes(".conflict-"));
+    expect(litter).toHaveLength(0);
+  });
+
   it("pre-primes new-file GET presigns before per-file created-by HEADs (avoids the presign-burst breaker trip)", async () => {
     vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
       { key: "alpha.md", size: 10, lastModified: new Date(), etag: '"a1"' },
@@ -832,6 +954,192 @@ describe("sync", () => {
     expect(journal.files[trackedKey]).toBeUndefined();
   });
 
+  it("local journal tombstone suppresses drift-restore: a deleted-but-still-remote key is NOT re-downloaded (no respawn)", async () => {
+    // Repro of the intermittent delete-respawn: the user deleted a clean file,
+    // its delete has not (yet) cleared the S3 object, and the SERVER
+    // FILE_TOMBSTONE fetch is degraded (empty map — the logged failure mode).
+    // The only intent record is the LOCAL journal tombstone (`removedAt`).
+    // The drift-restore path must honor it and NOT re-download the key.
+    const key = "docs/handoff.md";
+    const localPath = path.join(tmpDir, "companies", "acme", key);
+
+    // Remote still lists the object, etag matching the journal, lastModified
+    // BEFORE the local delete — a stale resurrection of a deleted key, not a
+    // genuine remote re-create.
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      {
+        key,
+        size: 42,
+        lastModified: new Date(Date.now() - 2 * 86_400_000),
+        etag: '"abc123"',
+      },
+    ]);
+    // Degraded-fetch case: server FILE_TOMBSTONE map is EMPTY.
+    setupFetchMock({ tombstones: [] });
+
+    // Local file ABSENT (user deleted it). Journal entry is a TOMBSTONE,
+    // recent enough to survive TTL GC.
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "2",
+        lastSync: "2026-06-19T00:00:00.000Z",
+        files: {
+          [key]: {
+            hash: "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
+            size: 42,
+            syncedAt: "2026-06-19T00:00:00.000Z",
+            direction: "down",
+            remoteEtag: "abc123",
+            removedAt: new Date().toISOString(),
+            removedReason: "local-delete",
+          },
+        },
+        pulls: [],
+      }),
+    );
+
+    await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      onEvent: () => {},
+    });
+
+    // The intentionally-deleted key must NOT be re-materialised.
+    expect(s3Module.downloadFile).not.toHaveBeenCalledWith(
+      expect.anything(),
+      key,
+      expect.anything(),
+    );
+    expect(fs.existsSync(localPath)).toBe(false);
+  });
+
+  it("pull producer: a single clean/current/non-divergent missing file is tombstoned (intentional delete), not drift-restored", async () => {
+    // The user deleted a genuinely-synced file. Its entry is clean (etag matches
+    // the current remote — currency holds), not divergent. The pull leg must
+    // treat the absence as an intentional delete: stamp a persisting
+    // `local-delete` tombstone and SKIP the re-download — not resurrect it.
+    const key = "docs/gone.md";
+    const localPath = path.join(tmpDir, "companies", "acme", key);
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key, size: 42, lastModified: new Date(), etag: '"cur123"' },
+    ]);
+    setupFetchMock({ tombstones: [] });
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "2",
+        lastSync: new Date().toISOString(),
+        files: {
+          [key]: {
+            hash: "h",
+            size: 42,
+            syncedAt: new Date().toISOString(),
+            direction: "down",
+            remoteEtag: "cur123",
+          },
+        },
+        pulls: [],
+      }),
+    );
+
+    await sync({ company: "acme", vaultConfig: mockConfig, hqRoot: tmpDir });
+
+    expect(s3Module.downloadFile).not.toHaveBeenCalledWith(
+      expect.anything(),
+      key,
+      expect.anything(),
+    );
+    expect(fs.existsSync(localPath)).toBe(false);
+    const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+    expect(journal.files[key]?.removedAt).toBeTruthy();
+    expect(journal.files[key]?.removedReason).toBe("local-delete");
+  });
+
+  it("pull producer: a BULK disappearance is drift-restored, NOT tombstoned (ridge-incident guard in the pull leg)", async () => {
+    // 12 clean files vanish at once (corrupt mirror / bulk rm / checkout). The
+    // bulk-asymmetry guard refuses to treat this as intent — every file is
+    // healed (re-downloaded), none tombstoned.
+    const keys = Array.from({ length: 12 }, (_, i) => `docs/f${i}.md`);
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce(
+      keys.map((k) => ({ key: k, size: 10, lastModified: new Date(), etag: `"e-${k}"` })),
+    );
+    setupFetchMock({ tombstones: [] });
+    const files: Record<string, unknown> = {};
+    for (const k of keys) {
+      files[k] = {
+        hash: "h",
+        size: 10,
+        syncedAt: new Date().toISOString(),
+        direction: "down",
+        remoteEtag: `e-${k}`,
+      };
+    }
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "2",
+        lastSync: new Date().toISOString(),
+        files,
+        pulls: [],
+      }),
+    );
+
+    await sync({ company: "acme", vaultConfig: mockConfig, hqRoot: tmpDir });
+
+    // All restored, none tombstoned.
+    expect(s3Module.downloadFile).toHaveBeenCalledTimes(12);
+    const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+    for (const k of keys) {
+      expect(journal.files[k]?.removedAt).toBeUndefined();
+    }
+  });
+
+  it("pull producer: a local-delete tombstone persists across pulls (not consumed/removed), so the delete stays propagatable", async () => {
+    // After the intentional-delete tombstone is stamped, a later pull must NOT
+    // drop the entry (the push leg still needs it to propagate the S3 delete).
+    // It stays skipped + preserved until the push propagates or TTL GC.
+    const key = "docs/gone.md";
+    const localPath = path.join(tmpDir, "companies", "acme", key);
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key, size: 42, lastModified: new Date(Date.now() - 2 * 86_400_000), etag: '"cur123"' },
+    ]);
+    setupFetchMock({ tombstones: [] });
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "2",
+        lastSync: new Date().toISOString(),
+        files: {
+          [key]: {
+            hash: "h",
+            size: 42,
+            syncedAt: new Date().toISOString(),
+            direction: "down",
+            remoteEtag: "cur123",
+            removedAt: new Date().toISOString(),
+            removedReason: "local-delete",
+          },
+        },
+        pulls: [],
+      }),
+    );
+
+    await sync({ company: "acme", vaultConfig: mockConfig, hqRoot: tmpDir });
+
+    expect(s3Module.downloadFile).not.toHaveBeenCalledWith(
+      expect.anything(),
+      key,
+      expect.anything(),
+    );
+    expect(fs.existsSync(localPath)).toBe(false);
+    const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+    // Entry PRESERVED as a tombstone, not removed.
+    expect(journal.files[key]?.removedAt).toBeTruthy();
+    expect(journal.files[key]?.removedReason).toBe("local-delete");
+  });
+
   it("aborts on --on-conflict abort", async () => {
     const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
     fs.mkdirSync(companyDocs, { recursive: true });

package/src/cli/sync.ts

@@ -34,6 +34,8 @@ import {
   normalizeEtag,
   migrateToV2,
   gcTombstones,
+  isTombstone,
+  tombstoneEntry,
   lastPullRecord,
   appendPullRecord,
   generatePullId,
@@ -69,6 +71,7 @@ import {
   readShortMachineId,
 } from "../lib/conflict-file.js";
 import { appendConflictEntry } from "../lib/conflict-index.js";
+import { isCloudAuthoritative } from "../lib/cloud-authoritative.js";
 import { reindex } from "./reindex.js";
 import { withOperationLock } from "../operation-lock.js";
 import {
@@ -212,7 +215,7 @@ export type SyncProgressEvent =
       path: string;
       journalEtag: string;
       remoteEtag: string;
-      reason: "stale-etag" | "legacy-no-etag" | "bulk-asymmetry";
+      reason: "stale-etag" | "legacy-no-etag" | "bulk-asymmetry" | "divergent-local";
     }
   | {
       /**
@@ -1048,6 +1051,19 @@ async function executeConflictItem(
 ): Promise<SyncResult | null> {
   const { remoteFile, localPath } = item;
 
+  // Cloud-authoritative paths (server-regenerated: company-brief.md, board.json,
+  // ontology/ signals/ sources/) are PULL-WINS: the cloud copy is the source of
+  // truth, so a divergence here is not a real conflict. Resolve it as a normal
+  // overwrite-from-cloud — queue a plain download (which stamps the journal with
+  // the REMOTE hash/etag) and skip the conflict path entirely. This removes both
+  // the `.conflict-` mirror loop AND the journal false-stamp (remote etag over
+  // divergent local content) that the keep path produced for these files.
+  if (isCloudAuthoritative(path.relative(run.hqRoot, localPath))) {
+    downloadItems.push({ action: "download", remoteFile, localPath, isNew: false });
+    run.emit({ type: "reconciled", path: remoteFile.key, direction: "pull" });
+    return null;
+  }
+
   await refreshRunContextIfExpiring(run);
 
   const detectedAt = new Date().toISOString();
@@ -1195,6 +1211,14 @@ async function executeConflictItem(
       remoteFile.etag,
       item.localMtime.getTime(),
     );
+    // Journal-honesty: we recorded the remote etag so this conflict can't
+    // re-fire (#137), but the KEPT local copy diverges from that remote — it
+    // never matched it. Flag the entry so the currency-gated delete planner
+    // refuses to propagate a delete for it (its currency would falsely match on
+    // HEAD, and the delete would destroy the divergent remote version). Any
+    // genuine future download clears the flag by replacing the entry.
+    const keptEntry = getEntry(run.journal, remoteFile.key);
+    if (keptEntry) keptEntry.localDiverges = true;
     return null;
   }
 
@@ -1724,6 +1748,15 @@ interface PullPlan {
  * caller (`sync()`) is responsible for emitting the resulting plan event
  * before iterating `items`.
  */
+// Pull-leg intentional-delete bulk-asymmetry breaker. Mirrors the push leg's
+// BULK_ASYMMETRY_* (share.ts): an abnormally large fraction of clean files
+// vanishing at once is a corrupt mirror / bulk op / unmount (the ridge-incident
+// class), not intent — so at/above the threshold the pull leg drift-restores
+// every candidate instead of tombstoning it. Below it, a missing clean file is
+// an intentional delete.
+const PULL_INTENTIONAL_DELETE_MIN_ABS = 10;
+const PULL_INTENTIONAL_DELETE_RATIO = 0.1;
+
 function computePullPlan(
   remoteFiles: RemoteFile[],
   journal: SyncJournal,
@@ -1744,6 +1777,12 @@ function computePullPlan(
   fileTombstones: ReadonlyMap<string, CompanyTombstone> = new Map(),
 ): PullPlan {
   const items: PullPlanItem[] = [];
+  // Clean/current/non-divergent files missing locally — collected here, then
+  // resolved post-loop by the bulk-asymmetry decision (tombstone vs. restore).
+  const intentionalDeleteCandidates: Array<{
+    remoteFile: RemoteFile;
+    localPath: string;
+  }> = [];
 
   for (const remoteFile of remoteFiles) {
     const localPath = resolveContainedVaultPath(companyRoot, remoteFile.key);
@@ -1837,6 +1876,23 @@ function computePullPlan(
     const tombstoneSuppresses =
       tombstone !== undefined &&
       !isRemoteRecreateAfterTombstone(remoteFile, tombstone);
+    // LOCAL journal tombstone — this machine's own intentional-delete record,
+    // independent of the (best-effort, intermittently-degraded) server
+    // FILE_TOMBSTONE fetch above. When a clean local delete is classified, the
+    // push leg stamps `removedAt` on the journal entry; honoring it here makes
+    // the delete-vs-drift-restore outcome DETERMINISTIC, closing the
+    // intermittent respawn where a degraded tombstone fetch let the pull leg
+    // re-materialize an intentionally-deleted file. Reuses the same re-create
+    // guard (a remote object newer than the local delete is a genuine re-create
+    // and still downloads). Consulted ONLY on the `!localExists` re-download
+    // path below — never to delete a file that is present locally.
+    const localTombstoneSuppresses =
+      journalEntry !== undefined &&
+      isTombstone(journalEntry) &&
+      journalEntry.removedAt !== undefined &&
+      !isRemoteRecreateAfterTombstone(remoteFile, {
+        deletedAt: journalEntry.removedAt,
+      });
 
     // lstat (not existsSync/statSync) handles three cases the legacy
     // checks got wrong for symlinks:
@@ -2060,15 +2116,67 @@ function computePullPlan(
     // re-create": the classic resurrection ("remote present → I'm behind →
     // download") the planner must NOT do. Route to `tombstone-delete` so the
     // executor drops any stale journal entry and the key stays gone, instead of
-    // pulling the deleted object back in.
-    if (tombstoneSuppresses) {
+    // pulling the deleted object back in. `localTombstoneSuppresses` adds the
+    // same protection driven by this machine's own journal tombstone, so an
+    // intentional delete is not resurrected even when the server FILE_TOMBSTONE
+    // fetch is degraded.
+    if (tombstoneSuppresses || localTombstoneSuppresses) {
+      // A persisting `local-delete` tombstone (stamped by the intentional-delete
+      // producer below) must KEEP its journal entry — the push leg still needs
+      // it to propagate the S3 delete. Skip the re-download without dropping the
+      // entry. Other tombstone kinds (scope-shrink / FILE_TOMBSTONE) drop it.
+      if (journalEntry?.removedReason === "local-delete") {
+        continue;
+      }
       items.push({ action: "tombstone-delete", remoteFile, localPath });
       continue;
     }
 
+    // Intentional-delete producer: a clean, CURRENT (etag matches), non-divergent
+    // file that is MISSING locally is the user deleting a genuinely-synced file.
+    // Collect it; the post-loop bulk-asymmetry decision tombstones it (intent) or
+    // restores it (mass loss = accident). A stale-etag, divergent, tombstoned, or
+    // never-journaled missing file falls through to the normal download below.
+    if (
+      !localExists &&
+      journalEntry !== undefined &&
+      !isTombstone(journalEntry) &&
+      !journalEntry.localDiverges &&
+      journalEntry.remoteEtag !== undefined &&
+      normalizeEtag(remoteFile.etag) === journalEntry.remoteEtag
+    ) {
+      intentionalDeleteCandidates.push({ remoteFile, localPath });
+      continue;
+    }
+
     items.push({ action: "download", remoteFile, localPath, isNew: !localExists });
   }
 
+  // ── Intentional-delete bulk-asymmetry decision (pull-leg producer) ─────────
+  // Below the breaker → stamp a persisting `local-delete` tombstone (the
+  // suppression above keeps it from being re-pulled; the push leg propagates the
+  // S3 delete on its next pass). At/above → drift-restore EVERY candidate: a
+  // mass disappearance (corrupt mirror / bulk rm / checkout / unmount) is
+  // accidental loss, never intent (the ridge-incident guard).
+  const totalJournalEntries = Object.keys(journal.files).length;
+  const intentionalDeleteIsBulk =
+    intentionalDeleteCandidates.length >= PULL_INTENTIONAL_DELETE_MIN_ABS &&
+    totalJournalEntries > 0 &&
+    intentionalDeleteCandidates.length / totalJournalEntries >=
+      PULL_INTENTIONAL_DELETE_RATIO;
+  for (const cand of intentionalDeleteCandidates) {
+    if (intentionalDeleteIsBulk) {
+      items.push({
+        action: "download",
+        remoteFile: cand.remoteFile,
+        localPath: cand.localPath,
+        isNew: true,
+      });
+    } else {
+      tombstoneEntry(journal, cand.remoteFile.key, "local-delete");
+    }
+  }
+
   let filesToDownload = 0;
   let bytesToDownload = 0;
   let filesToSkip = 0;

package/src/journal.ts

@@ -537,7 +537,7 @@ export function appendPullRecord(
 export function tombstoneEntry(
   journal: SyncJournal,
   relativePath: string,
-  reason: "scope_shrink" | "narrow_apply" | "manual",
+  reason: "scope_shrink" | "narrow_apply" | "manual" | "local-delete",
   now: string = new Date().toISOString(),
 ): void {
   const entry = journal.files[relativePath];

package/src/lib/cloud-authoritative.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from "vitest";
+import { isCloudAuthoritative } from "./cloud-authoritative.js";
+
+describe("isCloudAuthoritative", () => {
+  it("matches server-regenerated root files (both path forms)", () => {
+    for (const p of [
+      "companies/indigo/company-brief.md",
+      "company-brief.md",
+      "companies/acme/board.json",
+      "board.json",
+    ]) {
+      expect(isCloudAuthoritative(p)).toBe(true);
+    }
+  });
+
+  it("matches the pipeline-authored dirs", () => {
+    for (const p of [
+      "companies/indigo/ontology/entities/concept/grok.md",
+      "ontology/entities/person/x.md",
+      "companies/indigo/signals/slack-dm/action_item/a.md",
+      "signals/decision/b.md",
+      "companies/indigo/sources/slack/T1-2.md",
+      "sources/meetings/m.md",
+    ]) {
+      expect(isCloudAuthoritative(p)).toBe(true);
+    }
+  });
+
+  it("does NOT match client-owned files", () => {
+    for (const p of [
+      "companies/indigo/skills/work-mesh/SKILL.md",
+      "companies/indigo/projects/company-agents/release/index.html",
+      "companies/indigo/workers/hq-notify/emails/notice.template.html",
+      "companies/indigo/knowledge/readme.md",
+      "company-brief.md.conflict-2026-06-18T00-00-00Z-501bc8.md", // a mirror, not the brief
+      "docs/handoff.md",
+    ]) {
+      expect(isCloudAuthoritative(p)).toBe(false);
+    }
+  });
+
+  it("normalizes windows separators", () => {
+    expect(isCloudAuthoritative("companies\\indigo\\ontology\\entities\\x.md")).toBe(true);
+  });
+});

package/src/lib/cloud-authoritative.ts

@@ -0,0 +1,59 @@
+/**
+ * Cloud-authoritative vault paths — files the SERVER regenerates and owns, so
+ * on a sync conflict the cloud version always wins (pull-wins) and NO
+ * `.conflict-` mirror is minted.
+ *
+ * Why this exists
+ * ---------------
+ * Some vault files are written/regenerated server-side on a schedule, not by
+ * the client:
+ *   - `company-brief.md`  — rewritten by the ontology gardener's brief-generator
+ *                           on every run.
+ *   - `board.json`        — rewritten by board automation.
+ *   - `ontology/**`, `signals/**`, `sources/**` — the gardener / sources+signals
+ *                           pipeline are the sole authors; clients only consume.
+ *
+ * A client that also holds these locally diverges from the server copy on
+ * essentially every sync. Under `--on-conflict keep` (what outposts run) that
+ * produced two compounding bugs:
+ *   1. CONFLICT LOOP — each sync minted a fresh `<file>.conflict-<ts>-<machine>`
+ *      mirror that was never cleaned up (e.g. ~50 `company-brief.md.conflict-*`
+ *      piled up on an outpost over a few days).
+ *   2. SILENT DRIFT — the keep path stamped the journal with the REMOTE etag
+ *      while leaving the divergent LOCAL content in place, so the journal
+ *      reported "in sync" forever and the file never reconciled.
+ *
+ * Treating these paths as cloud-authoritative resolves both: the conflict path
+ * short-circuits to a normal overwrite-from-cloud (correct journal stamp, no
+ * mirror), because for a server-owned file the cloud copy is the truth.
+ *
+ * Extending
+ * ---------
+ * Add a pattern to {@link CLOUD_AUTHORITATIVE_PATTERNS}. Patterns are matched
+ * against the VAULT-RELATIVE path (a leading `companies/<slug>/` is stripped
+ * first), so both call sites — the pull leg (hqRoot-relative
+ * `companies/<slug>/…`) and the push leg (company-relative `…`) — work.
+ */
+
+/** Vault-relative patterns for server-owned, cloud-wins files. */
+export const CLOUD_AUTHORITATIVE_PATTERNS: readonly RegExp[] = [
+  /^company-brief\.md$/,
+  /^board\.json$/,
+  /^ontology\//,
+  /^signals\//,
+  /^sources\//,
+];
+
+/**
+ * True iff `relPath` is a server-regenerated, cloud-authoritative vault file.
+ * Accepts either an hqRoot-relative path (`companies/<slug>/…`) or a
+ * vault-relative path (`…`); Windows separators are normalized.
+ */
+export function isCloudAuthoritative(relPath: string): boolean {
+  const vaultRel = relPath
+    .split("\\")
+    .join("/")
+    .replace(/^\.?\//, "")
+    .replace(/^companies\/[^/]+\//, "");
+  return CLOUD_AUTHORITATIVE_PATTERNS.some((re) => re.test(vaultRel));
+}

package/src/types.ts

@@ -71,7 +71,7 @@ export interface JournalEntry {
    * the same paths as orphans, then garbage-collected.
    */
   removedAt?: string;
-  removedReason?: "scope_shrink" | "narrow_apply" | "manual";
+  removedReason?: "scope_shrink" | "narrow_apply" | "manual" | "local-delete";
   /**
    * 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
@@ -80,6 +80,16 @@ export interface JournalEntry {
    * the entry becomes in-scope again.
    */
   outOfScopeProtected?: boolean;
+  /**
+   * Journal-honesty marker. Set when a conflict was resolved by KEEPing a local
+   * copy that diverges from the remote: the entry still records the remote
+   * `remoteEtag` (so the conflict can't re-fire — the #137 invariant), but the
+   * local bytes never matched that remote. The currency-gated delete planner
+   * refuses to propagate a delete for such an entry — its currency would
+   * falsely "match" on HEAD, and deleting would destroy the divergent remote
+   * version. Cleared by any genuine download (which makes local == remote).
+   */
+  localDiverges?: boolean;
 }
 
 /**