@indigoai-us/hq-cloud 6.12.4 → 6.12.5

package/dist/lib/cloud-authoritative.test.js

@@ -0,0 +1,42 @@
+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);
+    });
+});
+//# sourceMappingURL=cloud-authoritative.test.js.map

package/dist/lib/cloud-authoritative.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-authoritative.test.js","sourceRoot":"","sources":["../../src/lib/cloud-authoritative.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEhE,QAAQ,CAAC,sBAAsB,EAAE,GAAG,EAAE;IACpC,EAAE,CAAC,yDAAyD,EAAE,GAAG,EAAE;QACjE,KAAK,MAAM,CAAC,IAAI;YACd,mCAAmC;YACnC,kBAAkB;YAClB,2BAA2B;YAC3B,YAAY;SACb,EAAE,CAAC;YACF,MAAM,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oCAAoC,EAAE,GAAG,EAAE;QAC5C,KAAK,MAAM,CAAC,IAAI;YACd,oDAAoD;YACpD,+BAA+B;YAC/B,oDAAoD;YACpD,uBAAuB;YACvB,wCAAwC;YACxC,uBAAuB;SACxB,EAAE,CAAC;YACF,MAAM,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mCAAmC,EAAE,GAAG,EAAE;QAC3C,KAAK,MAAM,CAAC,IAAI;YACd,4CAA4C;YAC5C,6DAA6D;YAC7D,gEAAgE;YAChE,sCAAsC;YACtC,0DAA0D,EAAE,0BAA0B;YACtF,iBAAiB;SAClB,EAAE,CAAC;YACF,MAAM,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,CAAC,oBAAoB,CAAC,6CAA6C,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzF,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cloud",
-  "version": "6.12.4",
+  "version": "6.12.5",
   "description": "HQ by Indigo cloud sync engine — bidirectional S3 sync for mobile access",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/cli/share.ts

@@ -64,6 +64,7 @@ import {
   readShortMachineId,
 } from "../lib/conflict-file.js";
 import { appendConflictEntry } from "../lib/conflict-index.js";
+import { isCloudAuthoritative } from "../lib/cloud-authoritative.js";
 
 /**
  * Push-side fresh-collision convergence probe.
@@ -1260,6 +1261,16 @@ async function executeUploads(
       }
 
       if ((localChanged && remoteChanged) || isFreshCollision) {
+        // Cloud-authoritative paths (server-regenerated: company-brief.md,
+        // board.json, ontology/ signals/ sources/) are PULL-WINS. Never push the
+        // local copy over the server-owned version and never mint a `.conflict-`
+        // mirror — the pull leg overwrites local from cloud. Declining here is
+        // what stops the per-sync conflict-mirror loop on these files.
+        if (isCloudAuthoritative(relativePath)) {
+          run.emit({ type: "reconciled", path: relativePath, direction: "push" });
+          counters.filesSkipped++;
+          return;
+        }
         conflictPaths.push(relativePath);
 
         const resolution = await resolveConflictSerialized({

package/src/cli/sync.test.ts

@@ -451,6 +451,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"' },

package/src/cli/sync.ts

@@ -69,6 +69,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 {
@@ -1048,6 +1049,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();

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));
+}