@indigoai-us/hq-cloud 6.11.20 → 6.12.1

package/src/bin/sync-runner.test.ts

@@ -2290,16 +2290,16 @@ describe("personal slot fanout", () => {
     }
   });
 
-  it("G: personal slot includes companies/{slug}/ subdirs when cloud:false marker is set AND HQ_SYNC_LOCAL_COMPANIES_TO_PERSONAL=1, excluding _template + team-synced slugs + missing/cloud:true markers", async () => {
-    // Gate the new behavior: without this env var the runner falls back to
-    // the legacy "companies/ never enumerated" personal vault. Test H below
-    // pins the OFF case.
-    vi.stubEnv("HQ_SYNC_LOCAL_COMPANIES_TO_PERSONAL", "1");
+  it("G: personal slot includes local companies/{slug}/ subdirs by default, excluding _template + team-synced slugs + cloud:true markers", async () => {
+    // Local (non-cloud) companies sync to the personal vault unconditionally
+    // — no env-var gate. A missing/markerless company.yaml is INCLUDED; only
+    // _template, team-synced slugs, and an explicit cloud:true marker are
+    // excluded.
     const shareSpy = vi.fn().mockResolvedValue(defaultShareResult());
     const tmpHqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-runner-test-"));
     try {
       // Top-level personal-vault content — anchors the assertion that the
-      // existing top-level walk still runs alongside the new company-subdir
+      // existing top-level walk still runs alongside the company-subdir
       // discovery.
       fs.mkdirSync(path.join(tmpHqRoot, "knowledge"));
 
@@ -2312,10 +2312,10 @@ describe("personal slot fanout", () => {
         }
       };
       mkCompany("free-co", "cloud: false\nname: Free Co\n"); // INCLUDED
+      mkCompany("zilch", null); // INCLUDED — no company.yaml (default-on)
       mkCompany("acme", "cloud: false\n"); // EXCLUDED — team-synced (membership below)
-      mkCompany("_template", "cloud: false\n"); // EXCLUDED — hard-listed slug
-      mkCompany("cloud-team", "cloud: true\n"); // EXCLUDED — wrong marker
-      mkCompany("zilch", null); // EXCLUDED — no company.yaml at all
+      mkCompany("_template", null); // EXCLUDED — hard-listed slug
+      mkCompany("cloud-team", "cloud: true\n"); // EXCLUDED — cloud-backed marker
 
       const deps = makeDeps({
         createVaultClient: () =>
@@ -2347,17 +2347,17 @@ describe("personal slot fanout", () => {
         .map((p) => path.relative(tmpHqRoot, p))
         .sort();
 
-      // free-co MUST be present (cloud:false, no membership, not _template).
+      // free-co + zilch MUST be present (local, no membership, not _template).
       expect(rel).toContain(path.join("companies", "free-co"));
+      expect(rel).toContain(path.join("companies", "zilch"));
       // knowledge/ MUST still be present (top-level walk unchanged).
       expect(rel).toContain("knowledge");
 
-      // All other companies MUST be filtered out.
+      // Excluded companies MUST be filtered out.
       for (const forbidden of [
         path.join("companies", "acme"), // team-synced — goes to cmp_a's bucket
         path.join("companies", "_template"), // hard-listed
-        path.join("companies", "cloud-team"), // cloud:true
-        path.join("companies", "zilch"), // no marker
+        path.join("companies", "cloud-team"), // cloud:true marker
       ]) {
         expect(rel).not.toContain(forbidden);
       }
@@ -2382,21 +2382,20 @@ describe("personal slot fanout", () => {
     }
   });
 
-  it("H: with HQ_SYNC_LOCAL_COMPANIES_TO_PERSONAL unset, companies/ subdirs are NEVER added to the personal slot — even with a valid cloud:false marker", async () => {
-    // Explicitly assert the OFF case: the env var is the gate. Without it,
-    // a `cloud: false` marker is necessary-but-insufficient; the personal
-    // vault stays in its pre-5.20 shape (top-level entries only, never
-    // any company subdir). Defensive `unstub` in case a leaked stub from
-    // an earlier test bleeds into this one.
+  it("H: local company subdirs are added with NO env var set — inclusion is unconditional (no gate)", async () => {
+    // Regression guard against re-introducing a gate. The old behavior
+    // required HQ_SYNC_LOCAL_COMPANIES_TO_PERSONAL=1; that gate is removed.
+    // With the env var explicitly unset, a markerless local company MUST
+    // still be pushed to the personal vault. Defensive `unstub` in case a
+    // leaked stub from an earlier test bleeds into this one.
     vi.unstubAllEnvs();
     const shareSpy = vi.fn().mockResolvedValue(defaultShareResult());
     const tmpHqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-runner-test-"));
     try {
       fs.mkdirSync(path.join(tmpHqRoot, "knowledge"));
-      // Same fixture as G — but the gate is off, so free-co must NOT appear.
+      // A markerless local company — must appear even with no env var.
       const dir = path.join(tmpHqRoot, "companies", "free-co");
       fs.mkdirSync(dir, { recursive: true });
-      fs.writeFileSync(path.join(dir, "company.yaml"), "cloud: false\n");
 
       const deps = makeDeps({
         createVaultClient: () =>
@@ -2423,9 +2422,9 @@ describe("personal slot fanout", () => {
         .map((p) => path.relative(tmpHqRoot, p))
         .sort();
 
-      // free-co must NOT appear because the env-var gate is off.
-      expect(rel).not.toContain(path.join("companies", "free-co"));
-      // knowledge/ must still appear — the legacy top-level walk is unchanged.
+      // free-co MUST appear — inclusion is unconditional, no env gate.
+      expect(rel).toContain(path.join("companies", "free-co"));
+      // knowledge/ must still appear — the top-level walk is unchanged.
       expect(rel).toContain("knowledge");
     } finally {
       fs.rmSync(tmpHqRoot, { recursive: true, force: true });
@@ -2495,17 +2494,16 @@ describe("personal slot fanout", () => {
     }
   });
 
-  it("J: personal slot's syncFn (pull) receives includeLocalCompanies + teamSyncedSlugs; company slots receive neither", async () => {
+  it("J: personal slot's syncFn (pull) receives teamSyncedSlugs; company slots receive none", async () => {
     // Symmetric to test I (push-side decommissionPrefixes). The pull side
-    // needs the same context to:
-    //   • allow `companies/{cloud-false-slug}/...` keys through when the
-    //     operator opts in (HQ_SYNC_LOCAL_COMPANIES_TO_PERSONAL=1)
-    //   • drop `companies/{team-synced-slug}/...` orphans even when push-
-    //     side decommission hasn't run (e.g. pull-only mode)
+    // needs the team-synced slug set to drop `companies/{team-synced-slug}/...`
+    // orphans even when push-side decommission hasn't run (e.g. pull-only
+    // mode). There is no longer an includeLocalCompanies gate — inclusion is
+    // unconditional.
     //
     // Default direction for runRunner is "pull" so this test exercises
     // the pull call without needing --direction.
-    vi.stubEnv("HQ_SYNC_LOCAL_COMPANIES_TO_PERSONAL", "1");
+    vi.unstubAllEnvs();
     const syncSpy = vi.fn().mockResolvedValue(defaultSyncResult());
     try {
       const deps = makeDeps({
@@ -2528,26 +2526,24 @@ describe("personal slot fanout", () => {
       const code = await runRunner(["--companies"], deps);
       expect(code).toBe(0);
 
-      // Personal slot: both args present, populated with the team-synced
-      // slug set + the env-var-derived gate flag.
+      // Personal slot: teamSyncedSlugs present, populated with the team-synced
+      // slug set. No includeLocalCompanies key (the gate is gone).
       const personalCall = (syncSpy.mock.calls as Array<[SyncOptions]>).find(
         (c) => c[0].company?.startsWith("prs_"),
       );
       expect(personalCall).toBeDefined();
       const personalArgs = personalCall![0] as SyncOptions & {
-        includeLocalCompanies?: boolean;
         teamSyncedSlugs?: ReadonlySet<string>;
       };
-      expect(personalArgs.includeLocalCompanies).toBe(true);
+      expect(Object.keys(personalArgs)).not.toContain("includeLocalCompanies");
       expect(Array.from(personalArgs.teamSyncedSlugs ?? []).sort()).toEqual([
         "acme",
         "beta",
       ]);
 
-      // Company slots: NEITHER key present (preserves the contract that
-      // company-target args stay identical to pre-Slice-2 shape — symmetric
-      // to test C's personalMode/journalSlug pin and test I's
-      // decommissionPrefixes pin).
+      // Company slots: no teamSyncedSlugs key (preserves the contract that
+      // company-target args stay identical — symmetric to test C's
+      // personalMode/journalSlug pin and test I's decommissionPrefixes pin).
       const companyCalls = (syncSpy.mock.calls as Array<[SyncOptions]>).filter(
         (c) => c[0].company?.startsWith("cmp_"),
       );
@@ -2561,41 +2557,6 @@ describe("personal slot fanout", () => {
     }
   });
 
-  it("K: personal slot's syncFn (pull) sets includeLocalCompanies=false when env var is unset — pull stays in legacy shape", async () => {
-    // Symmetric to test H (env-var-OFF case for push). Without the gate,
-    // the pull side preserves the pre-5.20 "drop all companies/... keys"
-    // contract regardless of what's actually in the personal bucket.
-    // Defensive unstub in case a previous test leaked a stub.
-    vi.unstubAllEnvs();
-    const syncSpy = vi.fn().mockResolvedValue(defaultSyncResult());
-    const deps = makeDeps({
-      createVaultClient: () =>
-        makeVaultStub({
-          memberships: [{ companyUid: "cmp_a" }],
-          entityGet: (uid: string) =>
-            Promise.resolve({ uid, slug: "acme" } as unknown as EntityInfo),
-          listPersons: () => Promise.resolve([olderPerson]),
-        }),
-      sync: syncSpy,
-    });
-
-    const code = await runRunner(["--companies"], deps);
-    expect(code).toBe(0);
-
-    const personalCall = (syncSpy.mock.calls as Array<[SyncOptions]>).find(
-      (c) => c[0].company?.startsWith("prs_"),
-    );
-    expect(personalCall).toBeDefined();
-    const personalArgs = personalCall![0] as SyncOptions & {
-      includeLocalCompanies?: boolean;
-    };
-    // Explicitly false — not "undefined" — because the runner always
-    // computes the value from the env var, then spreads it for the
-    // personal slot regardless of the value (allows downstream to know
-    // the gate was evaluated, not just "caller forgot to set it").
-    expect(personalArgs.includeLocalCompanies).toBe(false);
-  });
-
   it("F: shareFn paths for company slots stay [hqRoot/companies/{slug}] with no personalMode/journalSlug keys", async () => {
     const shareSpy = vi.fn().mockResolvedValue(defaultShareResult());
     const tmpHqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-runner-test-"));

package/src/cli/sync.test.ts

@@ -895,7 +895,7 @@ describe("sync", () => {
     expect(fs.existsSync(journalPath)).toBe(false);
   });
 
-  it("personalMode: true skips companies/* keys and downloads root keys to hqRoot", async () => {
+  it("personalMode: downloads local companies/* keys and root keys to hqRoot by default", async () => {
     vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
       { key: "companies/foo/bar.md", size: 50, lastModified: new Date(), etag: '"xyz789"' },
       { key: "docs/readme.md",       size: 30, lastModified: new Date(), etag: '"abc000"' },
@@ -906,22 +906,24 @@ describe("sync", () => {
       vaultConfig: mockConfig,
       hqRoot: tmpDir,
       personalMode: true,
+      // No teamSyncedSlugs → foo is a local (non-cloud) company, downloaded.
     });
 
-    // Exact counts (regression-tight)
-    expect(result.filesSkipped).toBe(1);
-    expect(result.filesDownloaded).toBe(1);
+    // Exact counts (regression-tight): local company + root key both land.
+    expect(result.filesSkipped).toBe(0);
+    expect(result.filesDownloaded).toBe(2);
 
-    // companies/* must NOT land anywhere
+    // companies/foo (local, non-cloud) lands at <hqRoot>/companies/foo/bar.md,
+    // NOT double-nested under <hqRoot>/companies/<slug>/companies/...
+    expect(fs.existsSync(path.join(tmpDir, "companies", "foo", "bar.md"))).toBe(true);
     expect(fs.existsSync(path.join(tmpDir, "companies", "acme", "companies", "foo", "bar.md"))).toBe(false);
-    expect(fs.existsSync(path.join(tmpDir, "companies", "foo", "bar.md"))).toBe(false);
 
     // docs/readme.md MUST land at <hqRoot>/docs/readme.md (NOT <hqRoot>/companies/<slug>/docs/readme.md)
     expect(fs.existsSync(path.join(tmpDir, "docs", "readme.md"))).toBe(true);
     expect(fs.existsSync(path.join(tmpDir, "companies", "acme", "docs", "readme.md"))).toBe(false);
   });
 
-  it("personalMode: downloads + journals companies/manifest.yaml (carve-out round-trips) while still skipping other companies/* keys", async () => {
+  it("personalMode: downloads + journals companies/manifest.yaml (carve-out round-trips) while still skipping team-synced orphan keys", async () => {
     vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
       { key: "companies/foo/bar.md",    size: 50, lastModified: new Date(), etag: '"xyz789"' },
       { key: "companies/manifest.yaml", size: 40, lastModified: new Date(), etag: '"man111"' },
@@ -932,10 +934,12 @@ describe("sync", () => {
       vaultConfig: mockConfig,
       hqRoot: tmpDir,
       personalMode: true,
+      // foo is now cloud-backed (team-synced) → its key is a stale orphan.
+      teamSyncedSlugs: new Set(["foo"]),
     });
 
-    // The manifest is the lone companies/* exemption: it downloads; other
-    // companies/* keys are still dropped.
+    // The manifest always downloads (routing source-of-truth carve-out);
+    // the team-synced orphan key is dropped.
     expect(result.filesSkipped).toBe(1);
     expect(result.filesDownloaded).toBe(1);
     expect(fs.existsSync(path.join(tmpDir, "companies", "manifest.yaml"))).toBe(true);
@@ -1080,13 +1084,12 @@ describe("sync", () => {
     expect(kept.thread_path).toBe("workspace/threads/T-machineB.json");
   });
 
-  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.
+  it("personalMode: downloads companies/{local-slug}/... keys by default when slug NOT in teamSyncedSlugs", async () => {
+    // Local (non-cloud) companies sync to the personal vault by default.
+    // Machine A pushed `companies/free-co/notes.md` to the personal bucket;
+    // 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"' },
@@ -1097,7 +1100,6 @@ describe("sync", () => {
       vaultConfig: mockConfig,
       hqRoot: tmpDir,
       personalMode: true,
-      includeLocalCompanies: true,
       teamSyncedSlugs: new Set(),  // empty → no slug is "orphan"
     });
 
@@ -1107,21 +1109,20 @@ describe("sync", () => {
     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
+  it("personalMode: drops companies/{team-synced-slug}/... keys as orphans (company became cloud-true)", async () => {
+    // The orphan-cleanup half. Once a company becomes cloud-true, 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` 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.
+      // Legitimate local content: download.
       { key: "companies/free-co/notes.md", size: 30, lastModified: new Date(), etag: '"new"' },
     ]);
 
@@ -1130,7 +1131,6 @@ describe("sync", () => {
       vaultConfig: mockConfig,
       hqRoot: tmpDir,
       personalMode: true,
-      includeLocalCompanies: true,
       teamSyncedSlugs: new Set(["acme"]),
     });
 
@@ -1142,18 +1142,16 @@ describe("sync", () => {
     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.
+  it("personalMode: companies/manifest.yaml always downloads (routing source-of-truth), even when other slugs are team-synced", async () => {
+    // The manifest is the one `companies/...` key carved into the personal
+    // vault unconditionally. It must round-trip on pull even when the
+    // operator has team-synced slugs (its key segment `manifest.yaml` is
+    // not a real slug and must never be treated as an orphan).
     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"' },
+      { key: "companies/manifest.yaml", size: 40, lastModified: new Date(), etag: '"m"' },
+      // A team-synced orphan that must still be dropped.
+      { key: "companies/acme/file.md",  size: 50, lastModified: new Date(), etag: '"o"' },
+      { key: "docs/readme.md",          size: 30, lastModified: new Date(), etag: '"d"' },
     ]);
 
     const result = await sync({
@@ -1161,13 +1159,13 @@ describe("sync", () => {
       vaultConfig: mockConfig,
       hqRoot: tmpDir,
       personalMode: true,
-      // includeLocalCompanies omitted → defaults to false
-      teamSyncedSlugs: new Set(["unrelated"]),
+      teamSyncedSlugs: new Set(["acme"]),
     });
 
-    expect(result.filesDownloaded).toBe(1);
+    expect(result.filesDownloaded).toBe(2);
     expect(result.filesSkipped).toBe(1);
-    expect(fs.existsSync(path.join(tmpDir, "companies", "anything", "file.md"))).toBe(false);
+    expect(fs.existsSync(path.join(tmpDir, "companies", "manifest.yaml"))).toBe(true);
+    expect(fs.existsSync(path.join(tmpDir, "companies", "acme", "file.md"))).toBe(false);
     expect(fs.existsSync(path.join(tmpDir, "docs", "readme.md"))).toBe(true);
   });
 

package/src/cli/sync.ts

@@ -323,35 +323,21 @@ export interface SyncOptions {
   onEvent?: (event: SyncProgressEvent) => void;
   /**
    * When true, the caller is syncing against the caller's person-entity
-   * bucket. Pulled keys whose path starts with `companies/` are dropped
-   * by default (belt-and-braces — the person bucket should never contain
-   * those, and the runner must not write them into the user's company
-   * folders). See `includeLocalCompanies` for the opt-in escape hatch.
+   * bucket. Pulled keys whose path starts with `companies/` are local
+   * (non-cloud) companies that sync to the personal vault by default —
+   * they are allowed through EXCEPT for slugs in `teamSyncedSlugs` (which
+   * are cloud-backed orphans, see below). `companies/manifest.yaml` is
+   * always allowed (routing source-of-truth).
    */
   personalMode?: boolean;
-  /**
-   * Opt-in: when `personalMode === true`, allow `companies/{slug}/...` keys
-   * through the pull filter EXCEPT for slugs in `teamSyncedSlugs` (which
-   * are orphan remnants from a company that was promoted to its own team
-   * bucket and remain pre-decommission). Mirrors the push-side
-   * `HQ_SYNC_LOCAL_COMPANIES_TO_PERSONAL=1` gate: when an operator opts
-   * into the cloud:false → personal-bucket fallback on their machine,
-   * pull must also know about the new key shape on the OTHER machine that
-   * subscribes to those keys. Without this, the feature is push-only —
-   * the destination machine never sees the keys.
-   *
-   * Default false preserves the pre-5.20 behavior (drop all
-   * `companies/...` keys in personalMode).
-   */
-  includeLocalCompanies?: boolean;
   /**
    * Slugs of companies the operator has an active team-bucket Membership
-   * for. Only consulted when `personalMode === true` AND
-   * `includeLocalCompanies === true`: keys under `companies/{slug}/...`
-   * for any slug in this set are dropped as orphans from a pre-promotion
-   * personal-bucket fallback. The push-side decommission cycle eventually
-   * removes these from the bucket; this filter prevents them from
-   * re-downloading into the same disk paths the team-bucket pull manages.
+   * for. Only consulted when `personalMode === true`: keys under
+   * `companies/{slug}/...` for any slug in this set are dropped as orphans
+   * from a pre-promotion personal-bucket fallback (the company became
+   * cloud-true). The push-side decommission cycle removes these from the
+   * bucket; this filter prevents them from re-downloading into the same
+   * disk paths the team-bucket pull manages.
    */
   teamSyncedSlugs?: ReadonlySet<string>;
   /**
@@ -798,7 +784,6 @@ function planPull(run: PullRunContext): PullPlan {
     run.companyRoot,
     run.shouldSync,
     run.options.personalMode === true,
-    run.options.includeLocalCompanies === true,
     run.options.teamSyncedSlugs ?? null,
     run.currentPrefixSet,
     run.fileTombstones,
@@ -1729,7 +1714,6 @@ function computePullPlan(
   companyRoot: string,
   shouldSync: (filePath: string, isDir?: boolean) => boolean,
   personalMode: boolean,
-  includeLocalCompanies: boolean,
   teamSyncedSlugs: ReadonlySet<string> | null,
   // Coalesced, company-relative prefixes the pull is scoped to (US-005).
   // `[""]` (the `all`-mode value) covers everything via `isCoveredByAny`, so
@@ -1774,18 +1758,13 @@ function computePullPlan(
       // fall through to download + journal like any personal file.
       remoteFile.key !== PERSONAL_VAULT_MANIFEST_KEY
     ) {
-      // Default: drop every `companies/...` key — the legacy contract
-      // is that the personal bucket should never contain them.
-      //
-      // EXCEPTION: when the operator has opted into the cloud:false →
-      // personal-bucket fallback (HQ_SYNC_LOCAL_COMPANIES_TO_PERSONAL=1
-      // on this machine), keys under `companies/{slug}/...` are
-      // legitimate — they're content a peer machine pushed for a
-      // company whose `company.yaml` declares `cloud: false`. Allow
-      // them through EXCEPT for slugs the operator has an active team-
-      // bucket Membership for: those are orphan remnants from before
-      // the company was promoted, and downloading them would clash
-      // with the team-bucket pull at the same disk path.
+      // Local (non-cloud) companies sync to the personal vault: keys under
+      // `companies/{slug}/...` are legitimate content a peer machine pushed
+      // for a company that is not cloud-backed. Allow them through EXCEPT
+      // for slugs the operator has an active team-bucket Membership for:
+      // those are orphan remnants from before the company became cloud-true,
+      // and downloading them would clash with the team-bucket pull at the
+      // same disk path.
       //
       // Symmetric to the push-side `decommissionPrefixes` logic in
       // share.ts — both target the same orphan class, both honor the
@@ -1794,7 +1773,7 @@ function computePullPlan(
       const slug = remoteFile.key.split("/")[1] ?? "";
       const isTeamSyncedOrphan =
         teamSyncedSlugs !== null && slug !== "" && teamSyncedSlugs.has(slug);
-      if (!includeLocalCompanies || isTeamSyncedOrphan) {
+      if (isTeamSyncedOrphan) {
         items.push({ action: "skip-personal-mode", remoteFile, localPath });
         continue;
       }
@@ -2138,12 +2117,16 @@ function computePullPlan(
     if (remoteKeySet.has(posixKey)) continue;
     const localPath = resolveContainedVaultPath(companyRoot, key);
     if (localPath === null) continue;
-    // PersonalMode key gating — mirror the download branch.
+    // PersonalMode key gating — mirror the download branch. Local (non-cloud)
+    // company keys are tombstone-eligible (a peer's delete should propagate),
+    // but team-synced orphans are left alone (the team-bucket pull owns those
+    // disk paths), and the manifest — the routing source-of-truth — is never
+    // auto-tombstoned out of the personal vault.
     if (personalMode && key.startsWith("companies/")) {
       const slug = key.split("/")[1] ?? "";
       const isTeamSyncedOrphan =
         teamSyncedSlugs !== null && slug !== "" && teamSyncedSlugs.has(slug);
-      if (!includeLocalCompanies || isTeamSyncedOrphan) continue;
+      if (isTeamSyncedOrphan || key === PERSONAL_VAULT_MANIFEST_KEY) continue;
     }
     // Ephemeral keys are filtered both directions; never tombstone-
     // propagate a conflict-mirror.

package/src/object-io.test.ts

@@ -516,6 +516,25 @@ describe("PresignObjectIO.headObject", () => {
     expect(await io.headObject("gone")).toBeNull();
   });
 
+  it("returns null on a server-confirmed FILES_PRESIGN_NOT_FOUND (absence, not denial — no GET issued)", async () => {
+    // The presign lambda HEAD'd S3 and confirmed absence. Unlike a read
+    // DENIAL (Forbidden, below), this is unambiguous "object missing", so
+    // headObject reports absent (null) and the push creates the new object —
+    // never reaching a 403-masked presigned GET.
+    const { vault, setPresign } = makeVault();
+    setPresign([
+      {
+        key: "new.md",
+        op: "get",
+        error: "Object not found: 'new.md'",
+        code: "FILES_PRESIGN_NOT_FOUND",
+      },
+    ]);
+    const io = new PresignObjectIO(vault, COMPANY);
+    expect(await io.headObject("new.md")).toBeNull();
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
   it("throws Forbidden when presign denies the key — denial is NOT absence", async () => {
     // Regression: pre-fix this returned null ("absent"), which made
     // share.ts's push guard (`if (remoteMeta)`) skip every conflict check

package/src/object-io.ts

@@ -853,6 +853,17 @@ export class PresignObjectIO implements ObjectIO {
         throw err;
       }
       const row = results[0];
+      if (row?.code === "FILES_PRESIGN_NOT_FOUND") {
+        // The presign lambda HEAD'd S3 and confirmed the object does NOT
+        // exist — an unambiguous absence, distinct from the read DENIAL
+        // handled below. Report absent (null) so the push creates the new
+        // object. Without this, a brand-new file's first upload is blocked
+        // forever: its presigned GET 403s (S3 masks absence when the URL
+        // lacks `s3:ListBucket`) and routes through the access-denied skip
+        // path. The server's explicit NOT_FOUND is the ONLY safe absence
+        // signal — a 403 stays "unknown", never "missing" (see below).
+        return null;
+      }
       if (!row || row.error || !row.url) {
         // A per-key denial means the caller can't READ the key — it says
         // nothing about whether the object EXISTS. Pre-fix this returned