@indigoai-us/hq-cloud 5.31.0 → 5.33.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 });
@@ -2211,6 +2454,23 @@ describe("isEphemeralPath (conflict-mirror pattern contract)", () => {
     ["foo.conflict-2026-05-19T17-05-56Z-deadbeef.md", true],
     // Non-markdown extensions also valid (sh scripts, ts files, etc.).
     ["foo.sh.conflict-2026-05-19T17-05-56Z-abc123.sh", true],
+    // ── extensionless originals (regression: `path.extname('.gitignore')`
+    //    returns '' in Node, so `buildConflictPath` produces no trailing
+    //    `.<ext>` segment for hidden-but-extensionless files).
+    [".gitignore.conflict-2026-05-23T19-51-38Z-4dff71", true],
+    [".hqignore.conflict-2026-05-23T19-51-38Z-4dff71", true],
+    [".agents/skills.conflict-2026-05-19T17-07-01Z-0a513b", true],
+    // ── legacy "unknown" machine token (regression: hosts without
+    //    `~/.hq/menubar.json` pre-Fix-3 fell through to the literal string
+    //    `"unknown"`, which `[a-f0-9]+` refused. Producer side is closed in
+    //    `../lib/machine-id.ts`, but the regex still must filter the
+    //    already-on-disk legacy files so the next push removes them).
+    [".gitignore.conflict-2026-05-15T15-10-35Z-unknown", true],
+    [".agents/skills.conflict-2026-05-15T15-10-35Z-unknown", true],
+    ["notes.md.conflict-2026-05-15T15-10-35Z-unknown.md", true],
+    [".hq/install-manifest.json.conflict-2026-05-15T15-11-58Z-unknown.json", true],
+    // Multi-dot extension (e.g., archive tarballs that conflicted).
+    ["dump.conflict-2026-05-13T19-40-40Z-abc.tar.gz", true],
   ])("matches conflict mirror: %s", (p, expected) => {
     expect(isEphemeralPath(p)).toBe(expected);
   });
@@ -2224,17 +2484,20 @@ describe("isEphemeralPath (conflict-mirror pattern contract)", () => {
     ["conflict-resolution.md", false],
     ["my-conflict.md", false],
     ["foo.conflict-handler.md", false],
-    // Date-shaped but missing the trailing dot + extension (real conflicts
-    // always carry a file extension; the trailing `\.` in the pattern is the
-    // safety against bare-substring false positives).
-    ["foo.conflict-2026-05-13T19-40-40Z-abc", false],
-    // Wrong-case or non-hex machine hash.
+    // Wrong-case or non-hex/non-"unknown" machine hash.
     ["foo.conflict-2026-05-13T19-40-40Z-ZZZZZZ.md", false],
     // Wrong timestamp format (real conflicts use UTC ISO with Z suffix).
     ["foo.conflict-2026-05-13-abc123.md", false],
-    // Missing leading dot before "conflict" (this protects against legitimate
+    // Missing leading dot before "conflict" (protects against legitimate
     // files that happen to contain the word "conflict" mid-name).
     ["fooconflict-2026-05-13T19-40-40Z-abc.md", false],
+    // Extra trailing segments after the machine hash — the `$` anchor +
+    // `[^/]*` ext class ensure a conflict marker can't appear mid-path.
+    ["foo.conflict-2026-05-13T19-40-40Z-abc/extra/path", false],
+    ["foo.conflict-2026-05-13T19-40-40Z-abc-then-more-text", false],
+    // Bare "unknown"-like tokens that aren't the literal sentinel.
+    ["foo.conflict-2026-05-13T19-40-40Z-unknowing.md", false],
+    ["foo.conflict-2026-05-13T19-40-40Z-UNKNOWN.md", false],
   ])("rejects non-mirror: %s", (p, expected) => {
     expect(isEphemeralPath(p)).toBe(expected);
   });

package/src/cli/share.ts

@@ -32,8 +32,11 @@ import type { SyncProgressEvent } from "./sync.js";
 /**
  * Local-only ephemeral artifacts: conflict-mirror files written by the pull
  * leg whenever a 3-way merge keeps local AND wants to preserve the remote
- * version for inspection. Format: `<orig>.conflict-<ISO-utc>-<machineHash>.<ext>`
- * (e.g. `.claude/CLAUDE.md.conflict-2026-05-13T19-40-40Z-e5797a.md`).
+ * version for inspection. Format: `<orig>.conflict-<ISO-utc>-<machineHash>[.ext]`
+ * (e.g. `.claude/CLAUDE.md.conflict-2026-05-13T19-40-40Z-e5797a.md`,
+ * or `.gitignore.conflict-2026-05-13T19-40-40Z-e5797a` — extensionless
+ * originals produce no trailing dot, see `buildConflictPath` in
+ * `../lib/conflict-file.ts`).
  *
  * These files MUST never round-trip to S3 — they're local-only safety backups
  * the user reviews and deletes once the merge is resolved. Pre-fix, the push
@@ -42,13 +45,34 @@ import type { SyncProgressEvent } from "./sync.js";
  * deleted them locally (because pull-confirmation had stamped them as
  * `direction: "down"`). Net effect: a permanent litter ratchet on remote.
  *
+ * Two known producer-shapes the regex must accommodate (both observed on
+ * affected user trees prior to this fix):
+ *
+ *   1. **`unknown` machine token.** Pre-`<hqRoot>/.hq/machine-id`
+ *      provisioning (see `../lib/machine-id.ts`), hosts without
+ *      `~/.hq/menubar.json` — every Linux HQ Pro Outpost, every fresh CLI
+ *      install — fell through to the literal string `"unknown"` from the
+ *      old `readShortMachineId()` fallback. The letters `k`, `n`, `o`, `w`
+ *      live outside `[a-f]`, so the pre-fix `[a-f0-9]+` class refused those
+ *      filenames. They round-tripped to S3 as ordinary files (which IS the
+ *      "permanent litter ratchet" this module's contract was supposed to
+ *      prevent). The new machine-id provisioning closes the producer side,
+ *      but we still accept `unknown` here so legacy files already on disk
+ *      are filtered out by the next push.
+ *
+ *   2. **Extensionless originals.** `path.extname('.gitignore')` returns
+ *      `''` in Node, so `buildConflictPath` produces no trailing `.<ext>`
+ *      segment for hidden-but-extensionless files like `.gitignore`,
+ *      `.hqignore`, or any `.agents/skills`-style entry. The pre-fix `\.`
+ *      tail was mandatory, so those names slipped through.
+ *
  * Wire-points: (1) push walker — `collectFiles` / `walkDir` skip these so
  * they never upload; (2) `computeDeletePlan` — skip these so an already-
  * journaled mirror that's been deleted locally doesn't get included in the
  * regular delete plan (the dedicated reconcile path handles existing litter).
  */
 const EPHEMERAL_PATH_PATTERN =
-  /\.conflict-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z-[a-f0-9]+\./;
+  /\.conflict-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z-(?:[a-f0-9]+|unknown)(?:\.[^/]*)?$/;
 
 /**
  * Cheap pure check — pass the relative key OR a basename; either works. Used
@@ -331,6 +355,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 +598,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 +649,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 +793,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 +817,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 +852,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 +1462,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

@@ -326,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 });