@indigoai-us/hq-cloud 5.29.0 → 5.31.0

package/src/journal.test.ts

@@ -24,6 +24,8 @@ import {
   gcTombstones,
   generatePullId,
   TOMBSTONE_TTL_MS,
+  PERSONAL_VAULT_JOURNAL_SLUG,
+  migratePersonalVaultJournal,
 } from "./journal.js";
 import type { SyncJournal, PullRecord } from "./types.js";
 
@@ -422,4 +424,103 @@ describe("journal", () => {
       expect(j.files["bogus.md"]).toBeDefined();
     });
   });
+
+  // ── Personal-vault journal-slug collision fix ──────────────────────────────
+  //
+  // Root cause: the --companies fanout's personal-vault slot journaled under
+  // the literal slug "personal", colliding with the companies/personal
+  // company (entity slug "personal"). The two targets have different sync
+  // roots, so the company's whole-tree delete-plan walked the shared
+  // sync-journal.personal.json, resolved the vault's hq-root keys against
+  // hqRoot/companies/personal (where they don't exist), tombstoned them as
+  // "remote already 404", and dropped them — only for the vault slot to
+  // re-upload them next cycle (~190 .claude/skills/* files of churn/sync).
+  describe("PERSONAL_VAULT_JOURNAL_SLUG", () => {
+    it("is decoupled from the 'personal' company slug", () => {
+      expect(PERSONAL_VAULT_JOURNAL_SLUG).not.toBe("personal");
+    });
+
+    it("survives sanitizeSlug unchanged (no path/dot/empty mangling)", () => {
+      // getJournalPath runs the slug through sanitizeSlug; the sentinel must
+      // pass through verbatim (it is all [a-zA-Z0-9_-] and not all [_-]).
+      expect(getJournalPath(PERSONAL_VAULT_JOURNAL_SLUG)).toBe(
+        path.join(
+          stateDir,
+          `sync-journal.${PERSONAL_VAULT_JOURNAL_SLUG}.json`,
+        ),
+      );
+    });
+
+    it("maps to a different journal file than 'personal'", () => {
+      expect(getJournalPath(PERSONAL_VAULT_JOURNAL_SLUG)).not.toBe(
+        getJournalPath("personal"),
+      );
+    });
+  });
+
+  describe("migratePersonalVaultJournal", () => {
+    const legacyJournal = (): SyncJournal => ({
+      version: "2",
+      lastSync: "2026-05-22T00:00:00.000Z",
+      files: {
+        ".claude/skills/deep-plan/SKILL.md": {
+          hash: "abc123",
+          size: 42,
+          syncedAt: "2026-05-22T00:00:00.000Z",
+          direction: "up",
+        },
+      },
+      pulls: [],
+    });
+
+    it("seeds the reserved slug from the legacy 'personal' journal when absent", () => {
+      writeJournal("personal", legacyJournal());
+      expect(fs.existsSync(getJournalPath(PERSONAL_VAULT_JOURNAL_SLUG))).toBe(false);
+
+      migratePersonalVaultJournal();
+
+      expect(fs.existsSync(getJournalPath(PERSONAL_VAULT_JOURNAL_SLUG))).toBe(true);
+      const seeded = readJournal(PERSONAL_VAULT_JOURNAL_SLUG);
+      // The hq-root-relative vault entry is preserved so it is NOT re-uploaded.
+      expect(seeded.files[".claude/skills/deep-plan/SKILL.md"]).toEqual(
+        legacyJournal().files[".claude/skills/deep-plan/SKILL.md"],
+      );
+      // Legacy journal is left intact (still used by the companies/personal company).
+      expect(fs.existsSync(getJournalPath("personal"))).toBe(true);
+    });
+
+    it("is idempotent — does not clobber an existing reserved-slug journal", () => {
+      // Pre-existing reserved-slug journal with distinct content.
+      const existing: SyncJournal = {
+        version: "2",
+        lastSync: "2026-05-22T12:00:00.000Z",
+        files: {
+          "core/keep-me.md": {
+            hash: "keep",
+            size: 7,
+            syncedAt: "2026-05-22T12:00:00.000Z",
+            direction: "up",
+          },
+        },
+        pulls: [],
+      };
+      writeJournal(PERSONAL_VAULT_JOURNAL_SLUG, existing);
+      writeJournal("personal", legacyJournal());
+
+      migratePersonalVaultJournal();
+
+      const after = readJournal(PERSONAL_VAULT_JOURNAL_SLUG);
+      expect(after.files["core/keep-me.md"]).toBeDefined();
+      // The legacy entry was NOT copied over the existing reserved journal.
+      expect(after.files[".claude/skills/deep-plan/SKILL.md"]).toBeUndefined();
+    });
+
+    it("no-ops when the legacy 'personal' journal is absent", () => {
+      expect(fs.existsSync(getJournalPath("personal"))).toBe(false);
+
+      migratePersonalVaultJournal();
+
+      expect(fs.existsSync(getJournalPath(PERSONAL_VAULT_JOURNAL_SLUG))).toBe(false);
+    });
+  });
 });

package/src/journal.ts

@@ -60,6 +60,58 @@ export function getJournalPath(slug: string): string {
   );
 }
 
+/**
+ * Reserved journal slug for the personal-vault fanout slot in the `--companies`
+ * runner. The vault slot uploads the whole HQ overlay (`.claude/`, `core/`,
+ * `personal/`, …) and journals hq-root-relative keys; its `syncRoot` is the HQ
+ * root itself.
+ *
+ * It MUST NOT share a journal with any real cloud company. Previously the slot
+ * used the literal slug `"personal"`, which collided with the
+ * `companies/personal` company (whose entity slug is also `"personal"`). The
+ * two targets have different sync roots, so the company's whole-tree
+ * `computeDeletePlan` walked the shared `sync-journal.personal.json`, resolved
+ * the vault's hq-root keys against `hqRoot/companies/personal` (where they
+ * don't exist), tombstoned them as "remote already 404", and dropped them from
+ * the journal — only for the vault slot to re-upload them next cycle. ~190
+ * `.claude/skills/*` files churned every sync.
+ *
+ * This sentinel value can never be produced by a real company slug from the
+ * entity service (which yields URL-safe lowercase slugs without leading
+ * underscores), and it survives `sanitizeSlug` unchanged (only `[a-zA-Z0-9_-]`
+ * chars; the embedded letters keep it off the all-`[_-]` reject path).
+ */
+export const PERSONAL_VAULT_JOURNAL_SLUG = "__hq_personal_vault__";
+
+/**
+ * One-time seed migration for the personal-vault journal slug.
+ *
+ * Before this fix the personal-vault slot journaled under the slug
+ * `"personal"`. After the fix it journals under
+ * `PERSONAL_VAULT_JOURNAL_SLUG`. Without a seed, the first run under the new
+ * slug would start from an empty journal and re-upload the entire HQ overlay.
+ *
+ * To avoid that mass re-upload, this copies the legacy `sync-journal.personal.json`
+ * to `sync-journal.__hq_personal_vault__.json` exactly once: only when the new
+ * file does NOT exist and the legacy file DOES. Idempotent — a no-op when the
+ * new file already exists or the legacy file is absent.
+ *
+ * The legacy `personal` journal is left untouched (it is still the journal for
+ * the real `companies/personal` company). After the seed, both journals
+ * converge after one cleanup cycle: the legacy `personal` journal tombstones
+ * the now-foreign hq-root keys once; the new vault journal tombstones any
+ * companies/personal-relative keys once. That single convergence pass is
+ * expected and harmless.
+ */
+export function migratePersonalVaultJournal(): void {
+  const newPath = getJournalPath(PERSONAL_VAULT_JOURNAL_SLUG);
+  if (fs.existsSync(newPath)) return;
+  const legacyPath = getJournalPath("personal");
+  if (!fs.existsSync(legacyPath)) return;
+  const legacy = readJournal("personal");
+  writeJournal(PERSONAL_VAULT_JOURNAL_SLUG, legacy);
+}
+
 /**
  * Read a per-company journal from disk.
  *

package/src/s3.test.ts

@@ -629,4 +629,34 @@ describe("downloadFile", () => {
     expect(fs.lstatSync(localPath).isSymbolicLink()).toBe(true);
     expect(fs.readlinkSync(localPath)).toBe("fresh-target.md");
   });
+
+  it("returns the object's user-metadata (including created-by) for a regular file", async () => {
+    nextGetObjectResponse = {
+      Body: (async function* () {
+        yield new Uint8Array([104, 105]); // "hi"
+      })(),
+      Metadata: { "created-by": "alice@example.com", "created-by-sub": "sub-123" },
+    };
+
+    const localPath = path.join(tmpRoot, "authored.md");
+    const result = await downloadFile(makeCtx(), "authored.md", localPath);
+
+    expect(result.metadata?.["created-by"]).toBe("alice@example.com");
+    expect(fs.readFileSync(localPath, "utf-8")).toBe("hi");
+  });
+
+  it("returns the object's user-metadata for a symlink record", async () => {
+    const localPath = path.join(tmpRoot, "authored-link.md");
+    nextGetObjectResponse = {
+      Body: (async function* () {
+        yield new Uint8Array();
+      })(),
+      Metadata: { "hq-symlink-target": "x", "created-by": "bob@example.com" },
+    };
+
+    const result = await downloadFile(makeCtx(), "authored-link.md", localPath);
+
+    expect(result.metadata?.["created-by"]).toBe("bob@example.com");
+    expect(fs.lstatSync(localPath).isSymbolicLink()).toBe(true);
+  });
 });

package/src/s3.ts

@@ -279,11 +279,20 @@ export async function uploadSymlink(
   return { etag: response.ETag || "" };
 }
 
+/**
+ * Download an object to localPath and return its S3 user-metadata.
+ *
+ * Materializes regular files and symlink records (the symlink branch
+ * reconstructs the link from the body/marker). The GetObject response
+ * already carries `response.Metadata` (S3 lowercases keys), so we
+ * return it to callers — e.g. the pull loop reads `created-by` to
+ * attribute downloaded files to their author with zero extra network.
+ */
 export async function downloadFile(
   ctx: EntityContext,
   key: string,
   localPath: string,
-): Promise<void> {
+): Promise<{ metadata?: Record<string, string> }> {
   const client = buildClient(ctx);
 
   const response = await client.send(
@@ -362,7 +371,7 @@ export async function downloadFile(
       }
     }
     fs.symlinkSync(symlinkTarget, localPath);
-    return;
+    return { metadata: response.Metadata };
   }
 
   // Symmetric to the symlink branch above: when a key was previously a
@@ -395,6 +404,7 @@ export async function downloadFile(
     chunks.push(Buffer.from(chunk));
   }
   fs.writeFileSync(localPath, Buffer.concat(chunks));
+  return { metadata: response.Metadata };
 }
 
 export interface RemoteFile {