@indigoai-us/hq-cloud 5.30.0 → 5.32.0

package/src/cli/share.test.ts

@@ -1799,6 +1799,249 @@ describe("share", () => {
   // exclusion list itself is enforced by the runner (sync-runner.ts) by only
   // passing in the allowed top-level directories — share() trusts its
   // `paths` input.
+
+  // ── Decommission prefixes ──────────────────────────────────────────────────
+  //
+  // `decommissionPrefixes` is the "company was promoted to its own team
+  // bucket, sweep its orphaned keys from this bucket" escape hatch. Unlike
+  // `propagateDeletes`, it does NOT require the local file to be missing —
+  // the caller asserts these keys no longer belong here regardless of
+  // local state. Honors the same `propagateDeletePolicy` safety property.
+
+  it("decommissionPrefixes: deletes journal entries under the prefix even when the local file is still present", async () => {
+    // Personal-bucket journal recording a key under companies/foo/. The
+    // local file is intentionally LEFT on disk to prove decommission
+    // doesn't depend on local-absence — the team bucket is now the
+    // canonical home but on-disk content is unchanged.
+    fs.mkdirSync(path.join(tmpDir, "companies", "foo"), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, "companies", "foo", "notes.md"), "still here");
+    fs.mkdirSync(path.join(tmpDir, "knowledge"), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, "knowledge", "x.md"), "knowledge");
+
+    const personalJournalPath = path.join(stateDir, "sync-journal.personal.json");
+    fs.writeFileSync(
+      personalJournalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "companies/foo/notes.md": {
+            hash: "h", size: 11, syncedAt: new Date().toISOString(),
+            direction: "up",
+          },
+          // Sibling out of decommission scope; must survive untouched.
+          "knowledge/x.md": {
+            hash: "k", size: 9, syncedAt: new Date().toISOString(),
+            direction: "up",
+          },
+        },
+      }),
+    );
+
+    const result = await share({
+      paths: [path.join(tmpDir, "knowledge")],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      personalMode: true,
+      journalSlug: "personal",
+      skipUnchanged: true,
+      // Pin owned-only — this test asserts the direction-of-origin gate
+      // applies symmetrically to decommission. Once the default flips to
+      // `currency-gated` (scheduled for 5.25+), the implicit-default form
+      // would force a HEAD call we don't want to mock here.
+      propagateDeletePolicy: "owned-only",
+      decommissionPrefixes: ["companies/foo"],
+    });
+
+    expect(result.filesDeleted).toBe(1);
+    expect(deleteRemoteFile).toHaveBeenCalledWith(expect.anything(), "companies/foo/notes.md");
+    expect(deleteRemoteFile).not.toHaveBeenCalledWith(expect.anything(), "knowledge/x.md");
+    // Local file remains on disk — decommission is a remote-only sweep.
+    expect(fs.existsSync(path.join(tmpDir, "companies", "foo", "notes.md"))).toBe(true);
+    // Journal entry pruned in lockstep with the remote delete.
+    const journalAfter = JSON.parse(fs.readFileSync(personalJournalPath, "utf-8"));
+    expect(journalAfter.files["companies/foo/notes.md"]).toBeUndefined();
+    expect(journalAfter.files["knowledge/x.md"]).toBeDefined();
+  });
+
+  it("decommissionPrefixes: under owned-only policy, skips direction:'down' entries", async () => {
+    // The orphan was pulled from another machine, never uploaded by this
+    // one. owned-only refuses to remotely erase another machine's upload
+    // even if the prefix list claims it. Mirrors propagateDeletes's
+    // owned-only contract — see test "propagateDeletes: under owned-only".
+    fs.mkdirSync(path.join(tmpDir, "companies", "foo"), { recursive: true });
+    const personalJournalPath = path.join(stateDir, "sync-journal.personal.json");
+    fs.writeFileSync(
+      personalJournalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "companies/foo/from-peer.md": {
+            hash: "h", size: 1, syncedAt: new Date().toISOString(),
+            direction: "down",
+          },
+        },
+      }),
+    );
+
+    const result = await share({
+      paths: [],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      personalMode: true,
+      journalSlug: "personal",
+      skipUnchanged: true,
+      propagateDeletePolicy: "owned-only",
+      decommissionPrefixes: ["companies/foo"],
+    });
+
+    expect(result.filesDeleted).toBe(0);
+    expect(deleteRemoteFile).not.toHaveBeenCalled();
+    // Journal entry preserved — the pulled-from-peer record stays so a
+    // future pull can still reconcile it correctly.
+    const journalAfter = JSON.parse(fs.readFileSync(personalJournalPath, "utf-8"));
+    expect(journalAfter.files["companies/foo/from-peer.md"]).toBeDefined();
+  });
+
+  it("decommissionPrefixes: dedupes with propagateDeletes plan — a key in both still emits one DeleteObject", async () => {
+    // If the local file is ALSO missing under the prefix, the same key
+    // would be eligible via both propagateDeletes (local gone) and
+    // decommissionPrefixes (prefix match). The dedup guarantee is that
+    // we delete once, not twice.
+    fs.mkdirSync(path.join(tmpDir, "companies", "foo"), { recursive: true });
+    // Note: NO file at companies/foo/notes.md — local-absence is what
+    // makes propagateDeletes plan it; the prefix is what makes
+    // decommission plan it. The Set-based dedup must collapse them.
+    const personalJournalPath = path.join(stateDir, "sync-journal.personal.json");
+    fs.writeFileSync(
+      personalJournalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "companies/foo/notes.md": {
+            hash: "h", size: 1, syncedAt: new Date().toISOString(),
+            direction: "up",
+          },
+        },
+      }),
+    );
+
+    const result = await share({
+      paths: [path.join(tmpDir, "companies", "foo")],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      personalMode: true,
+      journalSlug: "personal",
+      skipUnchanged: true,
+      propagateDeletes: true,
+      // Use "all" here so propagateDeletes plans the (already-missing)
+      // key regardless of its direction — the dedup assertion is what
+      // this test exists to pin.
+      propagateDeletePolicy: "all",
+      decommissionPrefixes: ["companies/foo"],
+    });
+
+    expect(result.filesDeleted).toBe(1);
+    expect(deleteRemoteFile).toHaveBeenCalledTimes(1);
+    expect(deleteRemoteFile).toHaveBeenCalledWith(expect.anything(), "companies/foo/notes.md");
+  });
+
+  it("decommissionPrefixes: under currency-gated policy, skips direction:'down' entries (same as owned-only)", async () => {
+    // currency-gated gates `propagateDeletes` on per-file HEAD currency
+    // proof. Decommission is unconditional by design — no HEAD check
+    // adds value — but we still want the direction-of-origin safety net
+    // so a peer-written entry isn't blasted away on the peer's behalf.
+    // Asserts `computeDecommissionPlan` collapses currency-gated to
+    // owned-only semantics (the requireOwned branch).
+    fs.mkdirSync(path.join(tmpDir, "companies", "foo"), { recursive: true });
+    const personalJournalPath = path.join(stateDir, "sync-journal.personal.json");
+    fs.writeFileSync(
+      personalJournalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "companies/foo/from-peer.md": {
+            hash: "h", size: 1, syncedAt: new Date().toISOString(),
+            direction: "down",
+            remoteEtag: "abc",
+          },
+        },
+      }),
+    );
+
+    const result = await share({
+      paths: [],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      personalMode: true,
+      journalSlug: "personal",
+      skipUnchanged: true,
+      propagateDeletePolicy: "currency-gated",
+      decommissionPrefixes: ["companies/foo"],
+    });
+
+    expect(result.filesDeleted).toBe(0);
+    expect(deleteRemoteFile).not.toHaveBeenCalled();
+  });
+
+  it("decommissionPrefixes: yields to toTombstone (key already 404 on remote) — single 'deleted' event, no double-count", async () => {
+    // Regression for an audit finding: a key in BOTH decommissionPlan
+    // AND deletePlan.toTombstone (because the remote was already 404 at
+    // HEAD time) used to double-emit a "deleted" event (one from the
+    // DeleteObject loop, one from the tombstone loop) and increment
+    // both filesDeleted and filesTombstoned. Fix: decommissionPlan
+    // dedups against toTombstone — the tombstone loop handles it
+    // (journal removal, no S3 call), decommission skips it.
+    fs.mkdirSync(path.join(tmpDir, "companies", "foo"), { recursive: true });
+    // No local file → propagateDeletes would normally plan it. With
+    // headRemoteFile mocked to return null (the default in beforeEach),
+    // currency-gated classifies as toTombstone (remote already 404).
+    const personalJournalPath = path.join(stateDir, "sync-journal.personal.json");
+    fs.writeFileSync(
+      personalJournalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "companies/foo/gone.md": {
+            hash: "h", size: 1, syncedAt: new Date().toISOString(),
+            direction: "up",
+            remoteEtag: "abc",
+          },
+        },
+      }),
+    );
+
+    const result = await share({
+      paths: [path.join(tmpDir, "companies", "foo")],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      personalMode: true,
+      journalSlug: "personal",
+      skipUnchanged: true,
+      propagateDeletes: true,
+      propagateDeletePolicy: "currency-gated",
+      decommissionPrefixes: ["companies/foo"],
+    });
+
+    // No DeleteObject — the tombstone bucket handled it (remote is 404).
+    expect(deleteRemoteFile).not.toHaveBeenCalled();
+    // Exactly one journal-removal counted (tombstone), not two.
+    expect(result.filesTombstoned).toBe(1);
+    expect(result.filesDeleted).toBe(0);
+    // Journal entry is gone.
+    const journalAfter = JSON.parse(fs.readFileSync(personalJournalPath, "utf-8"));
+    expect(journalAfter.files["companies/foo/gone.md"]).toBeUndefined();
+  });
+
   describe("personalMode", () => {
     it("personalMode=true keys files hq-root-relative, not companies/{slug}/-relative", async () => {
       fs.mkdirSync(path.join(tmpDir, ".claude", "skills"), { recursive: true });

package/src/cli/share.ts

@@ -331,6 +331,32 @@ export interface ShareOptions {
    * next push to erase it.
    */
   propagateDeletePolicy?: "currency-gated" | "owned-only" | "all";
+  /**
+   * Hq-root-relative key prefixes whose journal entries should be
+   * unconditionally decommissioned from the remote bucket and journal,
+   * independent of whether the local file is present. Each prefix matches
+   * its exact-key form (e.g. "companies/foo") AND any descendant key
+   * (e.g. "companies/foo/knowledge/notes.md") — same prefix semantics as
+   * `propagateDeletes`'s scope roots.
+   *
+   * Use case: a company that previously synced to the operator's personal
+   * bucket has been promoted to its own team bucket (`/designate-team`).
+   * Its keys at `companies/{slug}/...` in the personal bucket are now
+   * orphans — the on-disk files still exist (the team bucket is the new
+   * canonical home), so the standard `propagateDeletes` gate ("local file
+   * missing") never fires. This option asserts "these objects no longer
+   * belong in THIS bucket regardless of local state" and uses the same
+   * DeleteObject + journal-removal path as `propagateDeletes`.
+   *
+   * Honors `propagateDeletePolicy` — `"owned-only"` (default) only
+   * decommissions journal entries with `direction === "up"`, so a
+   * misconfigured caller never erases content pulled from elsewhere.
+   *
+   * Independent of `propagateDeletes`: callers can opt into decommission
+   * without enabling general delete propagation. In practice the runner
+   * sets both for the personal slot.
+   */
+  decommissionPrefixes?: string[];
   /**
    * Identity stamped onto each uploaded object's S3 user metadata
    * (`created-by`, `created-by-sub`, `created-at`). The hq-console vault UI
@@ -548,6 +574,43 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
       )
     : { toDelete: [], toTombstone: [], refusedStale: [] };
 
+  // Decommission plan: journal entries under explicit prefixes the caller
+  // has asserted no longer belong in this bucket (typically a promoted
+  // company's `companies/{slug}/` keys in the personal bucket). Independent
+  // of `propagateDeletes` and DOES NOT require the local file to be missing
+  // — the caller is making a stronger claim than "local says delete this".
+  // Honors the same owned-only safety policy so a misconfigured caller
+  // can never erase content the journal records as pulled from elsewhere.
+  // Dedupes against `deletePlan` so a key in both plans is only processed
+  // once (DeleteObject is idempotent on S3 but the journal-write would
+  // race a no-op pass through the loop body).
+  const decommissionPlan =
+    (options.decommissionPrefixes ?? []).length > 0
+      ? computeDecommissionPlan(
+          journal,
+          options.decommissionPrefixes ?? [],
+          propagateDeletePolicy,
+          // Dedup against `toDelete` (decommission and propagate-delete
+          // would both issue DeleteObject — single call wins) and against
+          // `toTombstone` (the remote is already 404; the tombstone loop
+          // drops the journal entry without a network call — decommission
+          // yields, both for efficiency and to avoid emitting two
+          // "deleted" events for the same key).
+          //
+          // We do NOT dedup against `refusedStale`. A key whose remote
+          // ETag drifted (peer wrote a newer version) but which decommission
+          // claims should still be removed — the caller has asserted this
+          // key doesn't belong in this bucket regardless of peer activity.
+          // Under owned-only (default) `computeDecommissionPlan`'s
+          // direction:'up' filter already excludes peer-written entries;
+          // under policy:'all' the caller has opted out of that safety
+          // anyway. The refusedStale loop below filters out keys we're
+          // about to decommission to avoid emitting a spurious "kept on
+          // remote" event for content we're deleting.
+          new Set([...deletePlan.toDelete, ...deletePlan.toTombstone]),
+        )
+      : [];
+
   emit({
     type: "plan",
     // share() is push-only; pull counts are sourced from sync()'s plan event.
@@ -562,8 +625,11 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     // Reported count is the deletes we're actually going to issue — does NOT
     // include tombstones (no S3 call) or refused-stale (no journal change).
     // Refusals surface as their own event stream so consumers that care can
-    // render a "kept on remote: N" line separately.
-    filesToDelete: deletePlan.toDelete.length,
+    // render a "kept on remote: N" line separately. `decommissionPlan` adds
+    // to this count because every decommission entry IS an issued
+    // DeleteObject (different intent than propagate-deletes, same network
+    // effect).
+    filesToDelete: deletePlan.toDelete.length + decommissionPlan.length,
   });
 
   // Stage 2: execute. Skip items pre-classified as no-ops, then for each
@@ -703,11 +769,16 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
 
   // Stage 3: propagate deletes. Three buckets, three actions:
   //
-  //   1. `toDelete` — write a delete-marker (versioning is enabled on the
-  //      bucket so the delete is soft and prior versions remain recoverable)
-  //      and remove the journal entry so the next sync sees the key as
-  //      truly gone on this machine. A failed DeleteObject leaves both
-  //      the journal entry and remote object intact — the next run retries.
+  //   1. `toDelete` (PLUS `decommissionPlan` concatenated in) — write a
+  //      delete-marker (versioning is enabled on the bucket so the delete
+  //      is soft and prior versions remain recoverable) and remove the
+  //      journal entry so the next sync sees the key as truly gone on
+  //      this machine. A failed DeleteObject leaves both the journal
+  //      entry and remote object intact — the next run retries.
+  //      Decommission keys join this bucket because their effect is
+  //      identical (DeleteObject + journal removal); the difference is
+  //      intent only, and the dedupe at plan-computation time ensures we
+  //      don't double-issue for a key both plans matched.
   //
   //   2. `toTombstone` — the remote was 404 at HEAD time (cleaned up out
   //      of band, e.g. someone hand-deleted via console). No DeleteObject
@@ -722,7 +793,7 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
   //      leg of `sync now` re-pulls naturally via the existing
   //      `hasRemoteChanged` path. Emit a dedicated event so UIs can
   //      surface the refusal without inferring it from absence.
-  for (const relativePath of deletePlan.toDelete) {
+  for (const relativePath of [...deletePlan.toDelete, ...decommissionPlan]) {
     if (vaultConfig && isExpiringSoon(ctx.expiresAt)) {
       ctx = await refreshEntityContext(companyRef, vaultConfig);
     }
@@ -757,7 +828,15 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
       message: "tombstone (remote already 404)",
     });
   }
+  // Decommission overrides refusedStale: a key whose peer drifted but
+  // which the caller has claimed via `decommissionPrefixes` is processed
+  // by the DeleteObject loop above; skip the refusal event here so the
+  // event stream doesn't simultaneously claim "we deleted it" and "we
+  // kept it on remote" for the same key.
+  const decommissionedSet =
+    decommissionPlan.length > 0 ? new Set(decommissionPlan) : null;
   for (const refused of deletePlan.refusedStale) {
+    if (decommissionedSet && decommissionedSet.has(refused.key)) continue;
     filesRefusedStale++;
     emit({
       type: "delete-refused-stale-etag",
@@ -1359,3 +1438,58 @@ async function computeDeletePlan(
 
   return plan;
 }
+
+/**
+ * Walk every journal key that matches one of the supplied `prefixes` and
+ * return the keys eligible for unconditional remote `DeleteObject`. Unlike
+ * `computeDeletePlan` this DOES NOT check whether the local file is missing
+ * — the caller has asserted that these keys no longer belong in this
+ * bucket regardless of local state (typically a company that was promoted
+ * from personal-bucket fallback to its own team bucket).
+ *
+ * An entry is in the plan only when ALL of the following hold:
+ *
+ *   1. Its key matches (or sits beneath) one of the `prefixes`. The match
+ *      is exact OR `key.startsWith(prefix + "/")` — same semantics as
+ *      `computeDeletePlan`'s scope-root check.
+ *   2. When `policy === "owned-only"`: the journal entry's `direction`
+ *      is `"up"` (this machine previously uploaded the file). Mirrors
+ *      `computeDeletePlan`'s safety property — a misconfigured prefix
+ *      list can never erase content pulled from elsewhere.
+ *   3. The key is NOT already in `alreadyPlanned` (the standard delete
+ *      plan), so a single DeleteObject + journal-update pass processes
+ *      each key once.
+ *
+ * Empty `prefixes` ⇒ empty plan (caller didn't opt in).
+ */
+function computeDecommissionPlan(
+  journal: SyncJournal,
+  prefixes: string[],
+  policy: "currency-gated" | "owned-only" | "all",
+  alreadyPlanned: ReadonlySet<string>,
+): string[] {
+  if (prefixes.length === 0) return [];
+  // `currency-gated` exists to gate `propagateDeletes` on per-file proof of
+  // currency (HEAD compare). Decommission is unconditional by design — we
+  // don't need a HEAD check to know whether the key belongs here, the
+  // caller has asserted it doesn't. So for the direction-of-origin safety
+  // gate we collapse `currency-gated` to the `owned-only` behavior:
+  // peer-written entries (direction:'down') are skipped. That's the
+  // conservative choice — a peer who wrote into this bucket should
+  // reconcile their own entry, not have us blast it away on their behalf.
+  const requireOwned = policy === "owned-only" || policy === "currency-gated";
+  const out: string[] = [];
+  for (const [relativeKey, entry] of Object.entries(journal.files)) {
+    if (alreadyPlanned.has(relativeKey)) continue;
+    const matches = prefixes.some(
+      (prefix) =>
+        prefix === "" ||
+        relativeKey === prefix ||
+        relativeKey.startsWith(`${prefix}/`),
+    );
+    if (!matches) continue;
+    if (requireOwned && entry.direction !== "up") continue;
+    out.push(relativeKey);
+  }
+  return out;
+}

package/src/cli/sync.test.ts

@@ -26,6 +26,7 @@ vi.mock("../s3.js", async () => {
       const dir = innerPath.dirname(localPath);
       if (!innerFs.existsSync(dir)) innerFs.mkdirSync(dir, { recursive: true });
       innerFs.writeFileSync(localPath, "mock file content");
+      return { metadata: {} };
     }),
     listRemoteFiles: innerVi.fn().mockResolvedValue(remoteFiles),
     deleteRemoteFile: innerVi.fn().mockResolvedValue(undefined),
@@ -325,6 +326,97 @@ describe("sync", () => {
     expect(fs.existsSync(path.join(tmpDir, "companies", "acme", "docs", "readme.md"))).toBe(false);
   });
 
+  it("personalMode + includeLocalCompanies: downloads companies/{cloud-false-slug}/... keys when slug NOT in teamSyncedSlugs", async () => {
+    // The symmetric flip for the cloud:false → personal-bucket fallback.
+    // Machine A pushed `companies/free-co/notes.md` to the personal bucket
+    // (because the operator set `HQ_SYNC_LOCAL_COMPANIES_TO_PERSONAL=1`
+    // AND `company.yaml` declares `cloud: false`). Machine B subscribes:
+    // pull must allow these keys through the personalMode filter, otherwise
+    // the feature is push-only and the destination machine never sees them.
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: "companies/free-co/notes.md", size: 50, lastModified: new Date(), etag: '"abc"' },
+      { key: "docs/readme.md",             size: 30, lastModified: new Date(), etag: '"def"' },
+    ]);
+
+    const result = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      personalMode: true,
+      includeLocalCompanies: true,
+      teamSyncedSlugs: new Set(),  // empty → no slug is "orphan"
+    });
+
+    expect(result.filesDownloaded).toBe(2);
+    expect(result.filesSkipped).toBe(0);
+    expect(fs.existsSync(path.join(tmpDir, "companies", "free-co", "notes.md"))).toBe(true);
+    expect(fs.existsSync(path.join(tmpDir, "docs", "readme.md"))).toBe(true);
+  });
+
+  it("personalMode + includeLocalCompanies: drops companies/{team-synced-slug}/... keys as orphans (symmetric to push-side decommission)", async () => {
+    // The orphan-cleanup half. Once a company has been promoted from
+    // cloud:false fallback to its own team bucket, the operator gains
+    // an active Membership for it (slug enters teamSyncedSlugs). Any
+    // leftover `companies/{that-slug}/...` keys in the personal bucket
+    // are stale residue — downloading them would clash with the team-
+    // bucket pull at the same disk path. Filter drops them silently.
+    // Push-side `decommissionPrefixes` eventually removes them from the
+    // bucket; this filter keeps the local tree clean in the meantime
+    // (especially important for pull-only mode where decommission never
+    // runs).
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      // Orphan: this slug is now team-synced — drop the key.
+      { key: "companies/acme/file.md",    size: 50, lastModified: new Date(), etag: '"old"' },
+      // Legitimate cloud:false content: download.
+      { key: "companies/free-co/notes.md", size: 30, lastModified: new Date(), etag: '"new"' },
+    ]);
+
+    const result = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      personalMode: true,
+      includeLocalCompanies: true,
+      teamSyncedSlugs: new Set(["acme"]),
+    });
+
+    expect(result.filesDownloaded).toBe(1);
+    expect(result.filesSkipped).toBe(1);
+    // acme orphan must NOT land — it would clash with the team-bucket pull.
+    expect(fs.existsSync(path.join(tmpDir, "companies", "acme", "file.md"))).toBe(false);
+    // free-co legitimate content lands at the hq-root-relative path.
+    expect(fs.existsSync(path.join(tmpDir, "companies", "free-co", "notes.md"))).toBe(true);
+  });
+
+  it("personalMode WITHOUT includeLocalCompanies: legacy behavior preserved — ALL companies/... keys dropped", async () => {
+    // Regression for the legacy contract. Pre-5.20 (and any operator who
+    // hasn't opted into HQ_SYNC_LOCAL_COMPANIES_TO_PERSONAL=1), the
+    // personal bucket should never contain `companies/...` keys. If they
+    // do exist (stale data, manual S3 console intervention, an old bug),
+    // the pull-side filter drops them as a safety net. This test pins
+    // that contract under the new option shape: includeLocalCompanies
+    // omitted → behaves identically to the original filter, even if
+    // teamSyncedSlugs is supplied.
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: "companies/anything/file.md", size: 50, lastModified: new Date(), etag: '"x"' },
+      { key: "docs/readme.md",             size: 30, lastModified: new Date(), etag: '"y"' },
+    ]);
+
+    const result = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      personalMode: true,
+      // includeLocalCompanies omitted → defaults to false
+      teamSyncedSlugs: new Set(["unrelated"]),
+    });
+
+    expect(result.filesDownloaded).toBe(1);
+    expect(result.filesSkipped).toBe(1);
+    expect(fs.existsSync(path.join(tmpDir, "companies", "anything", "file.md"))).toBe(false);
+    expect(fs.existsSync(path.join(tmpDir, "docs", "readme.md"))).toBe(true);
+  });
+
   it("overwrites local on --on-conflict overwrite", async () => {
     const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
     fs.mkdirSync(companyDocs, { recursive: true });
@@ -703,6 +795,64 @@ describe("sync", () => {
     expect(newFilesIdx).toBeGreaterThan(lastProgressIdx);
   });
 
+  it("stamps progress.author from the downloaded object's created-by metadata", async () => {
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: "docs/authored.md", size: 10, lastModified: new Date(), etag: '"e1"' },
+    ]);
+    vi.mocked(s3Module.downloadFile).mockImplementationOnce(
+      async (_ctx: unknown, _key: string, localPath: string) => {
+        const dir = path.dirname(localPath);
+        if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(localPath, "authored content");
+        return { metadata: { "created-by": "alice@example.com" } };
+      },
+    );
+
+    const progressEvents: Array<{ type: string; path: string; author?: string | null }> = [];
+    await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      onEvent: (e) => {
+        if (e.type === "progress") progressEvents.push(e);
+      },
+    });
+
+    expect(progressEvents).toHaveLength(1);
+    expect(progressEvents[0]).toMatchObject({
+      type: "progress",
+      path: "docs/authored.md",
+      author: "alice@example.com",
+    });
+  });
+
+  it("omits progress.author when the downloaded object has no created-by metadata", async () => {
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: "docs/anon.md", size: 10, lastModified: new Date(), etag: '"e2"' },
+    ]);
+    vi.mocked(s3Module.downloadFile).mockImplementationOnce(
+      async (_ctx: unknown, _key: string, localPath: string) => {
+        const dir = path.dirname(localPath);
+        if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(localPath, "anon content");
+        return { metadata: {} };
+      },
+    );
+
+    const progressEvents: Array<{ type: string; path: string; author?: string | null }> = [];
+    await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      onEvent: (e) => {
+        if (e.type === "progress") progressEvents.push(e);
+      },
+    });
+
+    expect(progressEvents).toHaveLength(1);
+    expect(progressEvents[0].author ?? null).toBeNull();
+  });
+
   it("plan event counts a 3-way conflict separately from downloads", async () => {
     // Local edit + journal-tracked + remote ETag drifted → conflict.
     const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
@@ -775,6 +925,7 @@ describe("sync", () => {
         if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
         // Mirror real downloadFile's symlink branch.
         fs.symlinkSync(linkTarget, localPath);
+        return { metadata: {} };
       },
     );
 
@@ -876,6 +1027,7 @@ describe("sync", () => {
         const dir = path.dirname(localPath);
         if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
         fs.symlinkSync(linkTarget, localPath);
+        return { metadata: {} };
       },
     );