@indigoai-us/hq-cloud 6.14.35 → 6.14.37

package/src/cli/share.test.ts

@@ -45,7 +45,7 @@ vi.mock("readline", () => ({
 }));
 
 import * as readline from "readline";
-import { share, _testing as shareTesting } from "./share.js";
+import { share, isForbiddenCompanyVaultKey, UnreachablePushPathsError, _testing as shareTesting } from "./share.js";
 import { deleteRemoteFile, downloadFile, headRemoteFile, uploadFile, uploadSymlink } from "../s3.js";
 import type { EntityContext } from "../types.js";
 import { VaultAuthError } from "../vault-client.js";
@@ -125,6 +125,220 @@ describe("wrapFilterWithIgnoreVisibility", () => {
   });
 });
 
+describe("resolveNamedPath (feedback_258e4a86 / feedback_a51cb63d)", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-resolve-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("returns absolute paths verbatim", () => {
+    const abs = path.join(tmpDir, "x.md");
+    expect(
+      shareTesting.resolveNamedPath(abs, tmpDir, path.join(tmpDir, "companies", "acme"), tmpDir),
+    ).toBe(abs);
+  });
+
+  it("resolves a company-relative path against the company folder when it does not exist under hqRoot", () => {
+    const syncRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(path.join(syncRoot, "knowledge", "agents"), { recursive: true });
+    const brief = path.join(syncRoot, "knowledge", "agents", "brief.md");
+    fs.writeFileSync(brief, "x");
+    // hqRoot base would be <tmpDir>/knowledge/agents/brief.md, which is absent;
+    // the syncRoot base resolves. This is the reporter's "company-relative
+    // spelling reaches nothing" case.
+    expect(shareTesting.resolveNamedPath("knowledge/agents/brief.md", tmpDir, syncRoot, tmpDir))
+      .toBe(brief);
+  });
+
+  it("resolves against the injected cwd when neither hqRoot nor the company folder has it", () => {
+    const syncRoot = path.join(tmpDir, "companies", "acme");
+    const workDir = path.join(tmpDir, "work");
+    fs.mkdirSync(workDir, { recursive: true });
+    fs.writeFileSync(path.join(workDir, "local.md"), "x");
+    // cwd is INJECTED, never read ambiently — no process.chdir in this suite.
+    expect(shareTesting.resolveNamedPath("local.md", tmpDir, syncRoot, workDir)).toBe(
+      path.join(workDir, "local.md"),
+    );
+  });
+
+  it("prefers the company folder over an hqRoot homonym outside the company tree", () => {
+    const syncRoot = path.join(tmpDir, "companies", "acme");
+    const workDir = path.join(tmpDir, "work");
+    for (const base of [tmpDir, syncRoot, workDir]) {
+      fs.mkdirSync(path.join(base, "knowledge"), { recursive: true });
+      fs.writeFileSync(path.join(base, "knowledge", "brief.md"), base);
+    }
+
+    // hqRoot/companies/acme is outside syncRoot's parent chain for tmpDir/knowledge,
+    // so the unrelated hq-root homonym is skipped and syncRoot wins.
+    expect(shareTesting.resolveNamedPath("knowledge/brief.md", tmpDir, syncRoot, workDir)).toBe(
+      path.join(syncRoot, "knowledge", "brief.md"),
+    );
+
+    // With the company copy gone, cwd is the last resort (hqRoot homonym still skipped).
+    fs.rmSync(path.join(syncRoot, "knowledge"), { recursive: true, force: true });
+    expect(shareTesting.resolveNamedPath("knowledge/brief.md", tmpDir, syncRoot, workDir)).toBe(
+      path.join(workDir, "knowledge", "brief.md"),
+    );
+  });
+
+  it("honors hqRoot-first precedence when the hqRoot hit is inside the company tree", () => {
+    const syncRoot = path.join(tmpDir, "companies", "acme");
+    const nested = path.join(syncRoot, "nested");
+    fs.mkdirSync(path.join(nested, "knowledge"), { recursive: true });
+    fs.writeFileSync(path.join(nested, "knowledge", "brief.md"), "nested");
+    fs.mkdirSync(path.join(syncRoot, "knowledge"), { recursive: true });
+    fs.writeFileSync(path.join(syncRoot, "knowledge", "brief.md"), "company");
+
+    expect(
+      shareTesting.resolveNamedPath("nested/knowledge/brief.md", syncRoot, syncRoot, syncRoot),
+    ).toBe(path.join(nested, "knowledge", "brief.md"));
+  });
+
+  it("falls back to the hqRoot base (preserving the 'does not exist' diagnostic) when nothing resolves", () => {
+    const syncRoot = path.join(tmpDir, "companies", "acme");
+    expect(shareTesting.resolveNamedPath("nope/missing.md", tmpDir, syncRoot, tmpDir)).toBe(
+      path.resolve(tmpDir, "nope/missing.md"),
+    );
+  });
+
+  it("defaults cwd to process.cwd() when the parameter is omitted", () => {
+    const syncRoot = path.join(tmpDir, "companies", "acme");
+    // Nothing exists under any base, so the fallback proves the signature is
+    // callable without the injected cwd (production call sites rely on it).
+    expect(shareTesting.resolveNamedPath("nope/missing.md", tmpDir, syncRoot)).toBe(
+      path.resolve(tmpDir, "nope/missing.md"),
+    );
+  });
+});
+
+describe("isWithinLexicalOrReal (feedback_258e4a86 / feedback_a51cb63d)", () => {
+  let tmpDir: string;
+  let hqRoot: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-within-test-"));
+    hqRoot = path.join(tmpDir, "hq");
+    fs.mkdirSync(hqRoot, { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("accepts an in-tree path reached through a symlinked ancestor (which realpath would reject)", () => {
+    const syncRoot = path.join(hqRoot, "companies", "acme");
+    fs.mkdirSync(syncRoot, { recursive: true });
+    const external = path.join(hqRoot, "repos", "knowledge-acme", "agents");
+    fs.mkdirSync(external, { recursive: true });
+    fs.writeFileSync(path.join(external, "brief.md"), "x");
+    fs.symlinkSync(path.join(hqRoot, "repos", "knowledge-acme"), path.join(syncRoot, "knowledge"));
+
+    const throughLink = path.join(syncRoot, "knowledge", "agents", "brief.md");
+    expect(shareTesting.isWithinLexicalOrReal(syncRoot, throughLink, hqRoot)).toBe(true);
+  });
+
+  it("still rejects a path that is genuinely outside the company folder", () => {
+    const syncRoot = path.join(hqRoot, "companies", "acme");
+    fs.mkdirSync(syncRoot, { recursive: true });
+    const outside = path.join(hqRoot, "outside", "stray.md");
+    fs.mkdirSync(path.dirname(outside), { recursive: true });
+    fs.writeFileSync(outside, "x");
+    expect(shareTesting.isWithinLexicalOrReal(syncRoot, outside, hqRoot)).toBe(false);
+  });
+
+  it("rejects a lexically-inside path whose realpath escapes the HQ tree entirely", () => {
+    // The lexical arm is what lets a symlinked ancestor through; without the
+    // hqRoot bound it would ALSO let `companies/acme/elsewhere/secret` upload
+    // bytes from anywhere on the machine under a company-namespaced key.
+    const syncRoot = path.join(hqRoot, "companies", "acme");
+    fs.mkdirSync(syncRoot, { recursive: true });
+    const foreign = path.join(tmpDir, "not-hq", "secrets");
+    fs.mkdirSync(foreign, { recursive: true });
+    fs.writeFileSync(path.join(foreign, "creds.txt"), "x");
+    fs.symlinkSync(foreign, path.join(syncRoot, "elsewhere"));
+
+    const escaping = path.join(syncRoot, "elsewhere", "creds.txt");
+    // Lexically inside the company folder…
+    const lexicalRel = path.relative(syncRoot, escaping);
+    expect(lexicalRel.startsWith("..")).toBe(false);
+    // …but the realpath leaves HQ, so it is refused.
+    expect(shareTesting.isWithinLexicalOrReal(syncRoot, escaping, hqRoot)).toBe(false);
+  });
+
+  // ── Tenant bound on the lexical arm ──────────────────────────────────────
+  //
+  // Bounding the lexical arm by hqRoot alone is NOT enough: hqRoot contains
+  // every other company, so a symlinked ancestor under companies/acme that
+  // points at another tenant's bytes would pass "lexically inside acme AND
+  // really inside HQ" and upload those bytes into acme's vault under an
+  // acme-namespaced key. The bound has to be the TENANT, not the tree.
+  it("rejects a lexically-inside path whose realpath lands in another company's folder", () => {
+    const syncRoot = path.join(hqRoot, "companies", "acme");
+    fs.mkdirSync(syncRoot, { recursive: true });
+    const otherSecrets = path.join(hqRoot, "companies", "other", "secret");
+    fs.mkdirSync(otherSecrets, { recursive: true });
+    fs.writeFileSync(path.join(otherSecrets, "creds.md"), "other tenant's bytes");
+    // A mislinked (or hostile) ancestor pointing straight at a sibling tenant.
+    fs.symlinkSync(otherSecrets, path.join(syncRoot, "knowledge"));
+
+    const crossTenant = path.join(syncRoot, "knowledge", "creds.md");
+    // Lexically inside acme, and its realpath is inside HQ — so only the
+    // tenant bound can refuse it.
+    expect(path.relative(syncRoot, crossTenant).startsWith("..")).toBe(false);
+    expect(shareTesting.isWithinLexicalOrReal(syncRoot, crossTenant, hqRoot)).toBe(false);
+  });
+
+  it("rejects a lexically-inside path whose realpath lands in another company's linked knowledge repo", () => {
+    // HQ topology pattern 2: a company's knowledge lives in its own repo under
+    // repos/private/ and is symlinked into the company folder. That target is
+    // outside every companies/<slug> root, so a companies-only bound would
+    // miss it — the sibling company's OWN link is what marks it as claimed.
+    const syncRoot = path.join(hqRoot, "companies", "acme");
+    fs.mkdirSync(syncRoot, { recursive: true });
+    const otherRoot = path.join(hqRoot, "companies", "other");
+    fs.mkdirSync(otherRoot, { recursive: true });
+    const otherRepo = path.join(hqRoot, "repos", "private", "knowledge-other");
+    fs.mkdirSync(otherRepo, { recursive: true });
+    fs.writeFileSync(path.join(otherRepo, "roadmap.md"), "other tenant's roadmap");
+    fs.symlinkSync(otherRepo, path.join(otherRoot, "knowledge"));
+    // acme's ancestor points at the sibling's repo (a typo away from its own).
+    fs.symlinkSync(otherRepo, path.join(syncRoot, "knowledge"));
+
+    const crossTenant = path.join(syncRoot, "knowledge", "roadmap.md");
+    expect(shareTesting.isWithinLexicalOrReal(syncRoot, crossTenant, hqRoot)).toBe(false);
+  });
+
+  it("still accepts the company's OWN linked knowledge repo when sibling tenants exist", () => {
+    // The tenant bound must not collapse the motivating topology: a sibling
+    // company being present (and publishing its own link) is not a reason to
+    // refuse acme's own linked subtree.
+    const syncRoot = path.join(hqRoot, "companies", "acme");
+    fs.mkdirSync(syncRoot, { recursive: true });
+    const otherRoot = path.join(hqRoot, "companies", "other");
+    fs.mkdirSync(otherRoot, { recursive: true });
+    const otherRepo = path.join(hqRoot, "repos", "private", "knowledge-other");
+    fs.mkdirSync(otherRepo, { recursive: true });
+    fs.symlinkSync(otherRepo, path.join(otherRoot, "knowledge"));
+
+    const acmeRepo = path.join(hqRoot, "repos", "private", "knowledge-acme", "agents");
+    fs.mkdirSync(acmeRepo, { recursive: true });
+    fs.writeFileSync(path.join(acmeRepo, "brief.md"), "x");
+    fs.symlinkSync(
+      path.join(hqRoot, "repos", "private", "knowledge-acme"),
+      path.join(syncRoot, "knowledge"),
+    );
+
+    const own = path.join(syncRoot, "knowledge", "agents", "brief.md");
+    expect(shareTesting.isWithinLexicalOrReal(syncRoot, own, hqRoot)).toBe(true);
+  });
+});
+
 const mockEntity = {
   uid: "cmp_01ABCDEF",
   slug: "acme",
@@ -336,17 +550,42 @@ describe("share", () => {
     expect(uploadFile).toHaveBeenCalledWith(expect.anything(), nested, "knowledge/crawl.json", undefined, expect.anything());
   });
 
-  it("skips files outside the company folder with a warning", async () => {
+  it("never uploads a file outside the company folder, and fails the push by default", async () => {
     const warnSpy = vi.spyOn(console, "error").mockImplementation(() => {});
     // File at hqRoot, outside companies/acme/
     const outsideFile = path.join(tmpDir, "stray.md");
     fs.writeFileSync(outsideFile, "stray");
 
+    // The per-path warning is unchanged; what changed (feedback_a51cb63d ask
+    // #2) is that an explicitly named, locally-present, unreachable path is no
+    // longer swallowed into a green "Pushed 0 file(s)".
+    await expect(
+      share({
+        paths: [outsideFile],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+      }),
+    ).rejects.toBeInstanceOf(UnreachablePushPathsError);
+
+    expect(uploadFile).not.toHaveBeenCalled();
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringMatching(/outside company folder/i),
+    );
+    warnSpy.mockRestore();
+  });
+
+  it("skips files outside the company folder with a warning under unreachablePathPolicy: 'warn'", async () => {
+    const warnSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const outsideFile = path.join(tmpDir, "stray.md");
+    fs.writeFileSync(outsideFile, "stray");
+
     const result = await share({
       paths: [outsideFile],
       company: "acme",
       vaultConfig: mockConfig,
       hqRoot: tmpDir,
+      unreachablePathPolicy: "warn",
     });
 
     expect(result.filesUploaded).toBe(0);
@@ -1735,6 +1974,7 @@ describe("share", () => {
           e.type === "scope-excluded" ||
           e.type === "scope-materialization-gap" ||
           e.type === "ignore-excluded" ||
+          e.type === "not-shipped" ||
           e.type === "delete-refused-bulk-asymmetry"
         ) return;
         events.push({
@@ -2556,6 +2796,115 @@ describe("share", () => {
     expect(journal.files["other/also-gone.md"]).toBeDefined();
   });
 
+  it("propagateDeletes: a company-relative directory spelling scopes deletes exactly like its absolute equivalent", async () => {
+    // Resolver symmetry (cluster ask #2). Delete scoping resolved named paths
+    // against hqRoot only, so `in-scope` — the same spelling `collectFiles`
+    // now accepts for upload — resolved to <hqRoot>/in-scope, did not exist,
+    // and was silently dropped from the scope. The result was a push whose
+    // upload leg honored the path and whose delete leg did not.
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(path.join(companyRoot, "in-scope"), { recursive: true });
+    fs.mkdirSync(path.join(companyRoot, "other"), { recursive: true });
+
+    const journalPath = path.join(stateDir, "sync-journal.acme.json");
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "in-scope/gone.md": {
+            hash: "h",
+            size: 1,
+            syncedAt: new Date().toISOString(),
+            direction: "up",
+            remoteEtag: "in-scope-etag",
+            kind: "file",
+            localDeleteIntent: deleteIntent("in-scope-etag", "h"),
+          },
+          "other/also-gone.md": {
+            hash: "h",
+            size: 1,
+            syncedAt: new Date().toISOString(),
+            direction: "up",
+            remoteEtag: "other-etag",
+            kind: "file",
+            localDeleteIntent: deleteIntent("other-etag", "h"),
+          },
+        },
+      }),
+    );
+
+    const result = await share({
+      paths: ["in-scope"], // company-relative, NOT hq-root-relative
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      skipUnchanged: true,
+      propagateDeletes: true,
+      propagateDeletePolicy: "owned-only",
+    });
+
+    expect(result.filesDeleted).toBe(1);
+    expect(deleteRemoteFile).toHaveBeenCalledWith(expect.anything(), "in-scope/gone.md");
+    const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+    expect(journal.files["in-scope/gone.md"]).toBeUndefined();
+    // Scope stays exactly as narrow as the absolute spelling's — no wider.
+    expect(journal.files["other/also-gone.md"]).toBeDefined();
+  });
+
+  it("propagateDeletes: a directory reached through a symlinked ancestor anchors NO delete scope", async () => {
+    // Deliberate asymmetry with the upload leg, and the reason delete scoping
+    // keeps realpath containment: a linked subtree's contents are never walked
+    // (they ship via their own repo), so treating it as a delete scope root
+    // would make every vault object under that prefix look locally absent and
+    // sweep it away. Narrower is the only safe direction here.
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const acmeRepo = path.join(tmpDir, "repos", "private", "knowledge-acme");
+    fs.mkdirSync(acmeRepo, { recursive: true });
+    fs.symlinkSync(acmeRepo, path.join(companyRoot, "knowledge"));
+
+    const journalPath = path.join(stateDir, "sync-journal.acme.json");
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          // Fully delete-eligible: current intent, matching etag, locally
+          // absent. The ONLY thing standing between it and a DeleteObject is
+          // that the linked directory anchors no scope — so a regression that
+          // widened delete containment would fail this test loudly.
+          "knowledge/agents/brief.md": {
+            hash: "h",
+            size: 1,
+            syncedAt: new Date().toISOString(),
+            direction: "up",
+            remoteEtag: "brief-etag",
+            kind: "file",
+            localDeleteIntent: deleteIntent("brief-etag", "h"),
+          },
+        },
+      }),
+    );
+
+    const result = await share({
+      paths: [path.join(companyRoot, "knowledge")],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      skipUnchanged: true,
+      propagateDeletes: true,
+      propagateDeletePolicy: "owned-only",
+    });
+
+    expect(result.filesDeleted).toBe(0);
+    expect(deleteRemoteFile).not.toHaveBeenCalled();
+    const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+    expect(journal.files["knowledge/agents/brief.md"]).toBeDefined();
+  });
+
   it("propagateDeletes: a failed DeleteObject leaves the journal entry intact for retry", async () => {
     const companyRoot = path.join(tmpDir, "companies", "acme");
     fs.mkdirSync(companyRoot, { recursive: true });
@@ -4200,6 +4549,424 @@ describe("share", () => {
     });
   });
 
+  // ── Push scope + visibility (feedback_258e4a86 / feedback_a51cb63d) ─────
+  //
+  // New local files under a synced subdir were invisible to every push path:
+  // a company-relative path resolved only against hqRoot ("does not exist"),
+  // an in-tree path reached through a symlinked ancestor was rejected as
+  // "outside company folder", and a directory symlink to an external repo
+  // swallowed its contents from every bucket — all while push still reported
+  // "Pushed 0 file(s)". These pin the resolver + visibility fixes.
+  describe("push scope + visibility (feedback_258e4a86 / feedback_a51cb63d)", () => {
+    it("resolves a company-relative push path against the company folder, not just hqRoot", async () => {
+      const companyRoot = path.join(tmpDir, "companies", "acme");
+      fs.mkdirSync(path.join(companyRoot, "knowledge", "agents"), { recursive: true });
+      const brief = path.join(companyRoot, "knowledge", "agents", "brief.md");
+      fs.writeFileSync(brief, "mission brief");
+
+      // Pre-fix: path.resolve(hqRoot, "knowledge/agents/brief.md") →
+      // <hqRoot>/knowledge/agents/brief.md, which does not exist → the file
+      // was reported "does not exist, skipping" and 0 uploaded no matter where
+      // the operator stood. The company-folder base now resolves it.
+      const result = await share({
+        paths: ["knowledge/agents/brief.md"],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+      });
+
+      expect(result.filesUploaded).toBe(1);
+      expect(result.unreachablePaths).toEqual([]);
+      expect(uploadFile).toHaveBeenCalledWith(
+        expect.anything(),
+        brief,
+        "knowledge/agents/brief.md",
+        undefined,
+        expect.anything(),
+      );
+    });
+
+    it("pushes an in-tree file reached through a symlinked ancestor (not 'outside company folder')", async () => {
+      const companyRoot = path.join(tmpDir, "companies", "acme");
+      fs.mkdirSync(companyRoot, { recursive: true });
+      const externalKnowledge = path.join(tmpDir, "repos", "private", "knowledge-acme", "agents");
+      fs.mkdirSync(externalKnowledge, { recursive: true });
+      fs.writeFileSync(path.join(externalKnowledge, "brief.md"), "mission brief");
+      // companies/acme/knowledge → repos/private/knowledge-acme (HQ pattern 2).
+      fs.symlinkSync(
+        path.join(tmpDir, "repos", "private", "knowledge-acme"),
+        path.join(companyRoot, "knowledge"),
+      );
+
+      // Explicitly name the in-tree file THROUGH the symlinked ancestor.
+      // Pre-fix, isWithin's realpath resolved it to repos/... → "outside
+      // company folder, skipping" and 0 uploaded, even though
+      // vaultKeyForLocalPath (lexical) would key it fine. It now uploads under
+      // its logical company-namespaced key.
+      const result = await share({
+        paths: [path.join(companyRoot, "knowledge", "agents", "brief.md")],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+      });
+
+      expect(result.filesUploaded).toBe(1);
+      expect(result.unreachablePaths).toEqual([]);
+      expect(uploadFile).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.anything(),
+        "knowledge/agents/brief.md",
+        undefined,
+        expect.anything(),
+      );
+    });
+
+    it("refuses a named push whose symlinked ancestor points at ANOTHER company's folder", async () => {
+      const companyRoot = path.join(tmpDir, "companies", "acme");
+      fs.mkdirSync(companyRoot, { recursive: true });
+      const otherSecrets = path.join(tmpDir, "companies", "other", "secret");
+      fs.mkdirSync(otherSecrets, { recursive: true });
+      fs.writeFileSync(path.join(otherSecrets, "creds.md"), "other tenant's bytes");
+      // Mislinked (or hostile) ancestor inside acme pointing at a sibling tenant.
+      fs.symlinkSync(otherSecrets, path.join(companyRoot, "knowledge"));
+
+      // Bounding the lexical containment arm by hqRoot alone would accept this
+      // — the path is lexically inside acme and its realpath is inside HQ —
+      // and upload company "other"'s bytes into acme's bucket under the
+      // acme-namespaced key "knowledge/creds.md". The bound is the tenant.
+      await expect(
+        share({
+          paths: [path.join(companyRoot, "knowledge", "creds.md")],
+          company: "acme",
+          vaultConfig: mockConfig,
+          hqRoot: tmpDir,
+        }),
+      ).rejects.toBeInstanceOf(UnreachablePushPathsError);
+
+      expect(uploadFile).not.toHaveBeenCalled();
+    });
+
+    it("refuses a named push whose symlinked ancestor points at another company's linked knowledge repo", async () => {
+      // The realistic HQ topology: each company's knowledge is its own repo
+      // under repos/private/, symlinked into the company folder. That target
+      // sits outside every companies/<slug> root, so a companies-only bound
+      // would let a typo'd link ship the sibling's repo into acme's vault.
+      const companyRoot = path.join(tmpDir, "companies", "acme");
+      fs.mkdirSync(companyRoot, { recursive: true });
+      const otherRoot = path.join(tmpDir, "companies", "other");
+      fs.mkdirSync(otherRoot, { recursive: true });
+      const otherRepo = path.join(tmpDir, "repos", "private", "knowledge-other");
+      fs.mkdirSync(otherRepo, { recursive: true });
+      fs.writeFileSync(path.join(otherRepo, "roadmap.md"), "other tenant's roadmap");
+      fs.symlinkSync(otherRepo, path.join(otherRoot, "knowledge"));
+      fs.symlinkSync(otherRepo, path.join(companyRoot, "knowledge"));
+
+      await expect(
+        share({
+          paths: [path.join(companyRoot, "knowledge", "roadmap.md")],
+          company: "acme",
+          vaultConfig: mockConfig,
+          hqRoot: tmpDir,
+        }),
+      ).rejects.toBeInstanceOf(UnreachablePushPathsError);
+
+      expect(uploadFile).not.toHaveBeenCalled();
+    });
+
+    it("still ships the company's OWN linked knowledge repo when a sibling tenant is present", async () => {
+      // Guard against over-correction: the tenant bound must not refuse the
+      // motivating topology just because another company exists locally.
+      const companyRoot = path.join(tmpDir, "companies", "acme");
+      fs.mkdirSync(companyRoot, { recursive: true });
+      const otherRoot = path.join(tmpDir, "companies", "other");
+      fs.mkdirSync(otherRoot, { recursive: true });
+      const otherRepo = path.join(tmpDir, "repos", "private", "knowledge-other");
+      fs.mkdirSync(otherRepo, { recursive: true });
+      fs.symlinkSync(otherRepo, path.join(otherRoot, "knowledge"));
+
+      const acmeRepo = path.join(tmpDir, "repos", "private", "knowledge-acme", "agents");
+      fs.mkdirSync(acmeRepo, { recursive: true });
+      fs.writeFileSync(path.join(acmeRepo, "brief.md"), "mission brief");
+      fs.symlinkSync(
+        path.join(tmpDir, "repos", "private", "knowledge-acme"),
+        path.join(companyRoot, "knowledge"),
+      );
+
+      const result = await share({
+        paths: [path.join(companyRoot, "knowledge", "agents", "brief.md")],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+      });
+
+      expect(result.filesUploaded).toBe(1);
+      expect(uploadFile).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.anything(),
+        "knowledge/agents/brief.md",
+        undefined,
+        expect.anything(),
+      );
+    });
+
+    it("separates own-link from foreign-link within a SINGLE push pass", async () => {
+      // The tenant-root lookup is memoized for the duration of one collect
+      // pass. This pins that the memo keys on the company being pushed rather
+      // than leaking one path's verdict onto the next: in one invocation the
+      // own linked repo ships and the sibling's linked repo does not.
+      const companyRoot = path.join(tmpDir, "companies", "acme");
+      fs.mkdirSync(companyRoot, { recursive: true });
+      const otherRoot = path.join(tmpDir, "companies", "other");
+      fs.mkdirSync(otherRoot, { recursive: true });
+
+      const otherRepo = path.join(tmpDir, "repos", "private", "knowledge-other");
+      fs.mkdirSync(otherRepo, { recursive: true });
+      fs.writeFileSync(path.join(otherRepo, "secret.md"), "other tenant bytes");
+      fs.symlinkSync(otherRepo, path.join(otherRoot, "knowledge"));
+      // acme ALSO links the sibling's repo in, under its own name.
+      fs.symlinkSync(otherRepo, path.join(companyRoot, "borrowed"));
+
+      const acmeRepo = path.join(tmpDir, "repos", "private", "knowledge-acme", "agents");
+      fs.mkdirSync(acmeRepo, { recursive: true });
+      fs.writeFileSync(path.join(acmeRepo, "brief.md"), "mission brief");
+      fs.symlinkSync(
+        path.join(tmpDir, "repos", "private", "knowledge-acme"),
+        path.join(companyRoot, "knowledge"),
+      );
+
+      const result = await share({
+        paths: [
+          path.join(companyRoot, "knowledge", "agents", "brief.md"),
+          path.join(companyRoot, "borrowed", "secret.md"),
+        ],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        // warn so the pass completes and both verdicts are observable at once;
+        // the default 'fail' path is covered by the tests above.
+        unreachablePathPolicy: "warn",
+      });
+
+      expect(result.filesUploaded).toBe(1);
+      expect(uploadFile).toHaveBeenCalledTimes(1);
+      expect(uploadFile).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.anything(),
+        "knowledge/agents/brief.md",
+        undefined,
+        expect.anything(),
+      );
+      expect(result.unreachablePaths).toEqual([
+        path.join(companyRoot, "borrowed", "secret.md"),
+      ]);
+    });
+
+    it("fails the push when an explicitly named path exists but is outside the company folder (not a silent 0-file success)", async () => {
+      const companyRoot = path.join(tmpDir, "companies", "acme");
+      fs.mkdirSync(companyRoot, { recursive: true });
+      fs.writeFileSync(path.join(companyRoot, "in-scope.md"), "shippable");
+      // A real file that lives OUTSIDE the company folder entirely.
+      const stray = path.join(tmpDir, "outside", "stray.md");
+      fs.mkdirSync(path.dirname(stray), { recursive: true });
+      fs.writeFileSync(stray, "outside content");
+
+      // Ask #2 of the report: "error, not warn-skip, when the named file
+      // exists locally but is unreachable by the resolver". Pre-fix this
+      // printed "✓ Pushed 0 file(s)" and exited 0.
+      const events: Array<{ type: string; reason?: string; count?: number }> = [];
+      await expect(
+        share({
+          paths: [stray, path.join(companyRoot, "in-scope.md")],
+          company: "acme",
+          vaultConfig: mockConfig,
+          hqRoot: tmpDir,
+          onEvent: (e) => events.push(e as { type: string; reason?: string; count?: number }),
+        }),
+      ).rejects.toBeInstanceOf(UnreachablePushPathsError);
+
+      // The failure is an ATOMIC no-op: it fires before any upload, so the
+      // reachable sibling in the same invocation is not half-shipped either.
+      expect(uploadFile).not.toHaveBeenCalled();
+      // Still visible on the event stream before the throw.
+      const notShipped = events.find(
+        (e) => e.type === "not-shipped" && e.reason === "unreachable-path",
+      );
+      expect(notShipped).toBeDefined();
+      expect(notShipped?.count).toBe(1);
+    });
+
+    it("names the offending path and its reason on the thrown error", async () => {
+      const companyRoot = path.join(tmpDir, "companies", "acme");
+      fs.mkdirSync(companyRoot, { recursive: true });
+      const stray = path.join(tmpDir, "outside", "stray.md");
+      fs.mkdirSync(path.dirname(stray), { recursive: true });
+      fs.writeFileSync(stray, "outside content");
+
+      let err: unknown;
+      try {
+        await share({
+          paths: [stray],
+          company: "acme",
+          vaultConfig: mockConfig,
+          hqRoot: tmpDir,
+        });
+      } catch (e) {
+        err = e;
+      }
+
+      expect(err).toBeInstanceOf(UnreachablePushPathsError);
+      const unreachable = err as UnreachablePushPathsError;
+      expect(unreachable.paths).toEqual([stray]);
+      expect(unreachable.reasons[stray]).toBe("outside-company");
+      // The operator gets the actionable topology hint, not just a code.
+      expect(unreachable.message).toContain("outside the company folder");
+    });
+
+    it("records rather than throws for an unreachable path under unreachablePathPolicy: 'warn'", async () => {
+      const companyRoot = path.join(tmpDir, "companies", "acme");
+      fs.mkdirSync(companyRoot, { recursive: true });
+      const stray = path.join(tmpDir, "outside", "stray.md");
+      fs.mkdirSync(path.dirname(stray), { recursive: true });
+      fs.writeFileSync(stray, "outside content");
+
+      // The sync runner walks roots it computed itself, not operator input, so
+      // it opts into the legacy warn behavior instead of failing a whole
+      // multi-company sync on one odd root.
+      const result = await share({
+        paths: [stray],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        unreachablePathPolicy: "warn",
+      });
+
+      expect(result.filesUploaded).toBe(0);
+      expect(result.unreachablePaths).toEqual([stray]);
+    });
+
+    it("surfaces a named path that does not exist under any base as unreachable without failing the run", async () => {
+      const companyRoot = path.join(tmpDir, "companies", "acme");
+      fs.mkdirSync(companyRoot, { recursive: true });
+
+      // "missing" is deliberately NOT fatal even under the default policy: a
+      // multi-company push plans one leg per membership, including companies
+      // whose folder was never materialized locally. Only "outside-company" —
+      // the report's "exists locally but unreachable" case — fails the run.
+      const result = await share({
+        paths: ["knowledge/agents/nope.md"],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+      });
+
+      expect(result.filesUploaded).toBe(0);
+      expect(result.unreachablePaths).toEqual(["knowledge/agents/nope.md"]);
+    });
+
+    it("reports unreachable paths using the caller's original spelling verbatim", async () => {
+      const companyRoot = path.join(tmpDir, "companies", "acme");
+      fs.mkdirSync(companyRoot, { recursive: true });
+
+      // Spelling contract: a relative token is echoed relative (never resolved
+      // to one of the probe bases), so an operator can match the reported path
+      // against the one they typed.
+      const relative = await share({
+        paths: ["knowledge/agents/nope.md"],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+      });
+      expect(relative.unreachablePaths).toEqual(["knowledge/agents/nope.md"]);
+
+      // …and an absolute token is echoed absolute.
+      const stray = path.join(tmpDir, "outside", "stray.md");
+      fs.mkdirSync(path.dirname(stray), { recursive: true });
+      fs.writeFileSync(stray, "outside content");
+      const absolute = await share({
+        paths: [stray],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        unreachablePathPolicy: "warn",
+      });
+      expect(absolute.unreachablePaths).toEqual([stray]);
+    });
+
+    it("reports a directory symlink to an external repo as a linked subtree not shipped to the vault", async () => {
+      const companyRoot = path.join(tmpDir, "companies", "acme");
+      fs.mkdirSync(companyRoot, { recursive: true });
+      const externalTarget = path.join(tmpDir, "repos", "private", "knowledge-acme");
+      fs.mkdirSync(externalTarget, { recursive: true });
+      fs.writeFileSync(path.join(externalTarget, "brief.md"), "lives in the repo");
+      fs.symlinkSync(externalTarget, path.join(companyRoot, "knowledge"));
+
+      const events: Array<{ type: string; reason?: string; samplePaths?: string[] }> = [];
+      const result = await share({
+        paths: [companyRoot],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        onEvent: (e) =>
+          events.push(e as { type: string; reason?: string; samplePaths?: string[] }),
+      });
+
+      // Topology contract preserved: only the link record ships; its external
+      // contents do NOT (no regular-file upload for brief.md).
+      expect(result.filesUploaded).toBe(1);
+      expect(uploadFile).not.toHaveBeenCalled();
+      // But the subtree is now VISIBLE instead of vanishing from every bucket.
+      expect(result.linkedSubtreesNotShipped).toEqual(["knowledge"]);
+      const notShipped = events.find(
+        (e) => e.type === "not-shipped" && e.reason === "linked-subtree",
+      );
+      expect(notShipped).toBeDefined();
+      expect(notShipped?.samplePaths).toEqual(["knowledge"]);
+    });
+
+    it("keeps a file explicitly pushed from under a linked subtree alive across a later full-walk push", async () => {
+      // The documented workaround for a linked subtree is `hq sync push
+      // <path>` — a point-in-time copy. That copy is only useful if the very
+      // next full-company sync does not immediately delete it again: the walk
+      // never descends the link, so the key has no walk-visible counterpart.
+      // Delete candidacy is lstat-based (the file IS on disk through the
+      // link), so the copy survives even the gate-free "all" policy.
+      const companyRoot = path.join(tmpDir, "companies", "acme");
+      fs.mkdirSync(companyRoot, { recursive: true });
+      const externalTarget = path.join(tmpDir, "repos", "private", "knowledge-acme");
+      fs.mkdirSync(path.join(externalTarget, "agents"), { recursive: true });
+      fs.writeFileSync(path.join(externalTarget, "agents", "brief.md"), "mission brief");
+      fs.symlinkSync(externalTarget, path.join(companyRoot, "knowledge"));
+
+      const pushed = await share({
+        paths: [path.join(companyRoot, "knowledge", "agents", "brief.md")],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+      });
+      expect(pushed.filesUploaded).toBe(1);
+
+      const journalPath = path.join(stateDir, "sync-journal.acme.json");
+      const afterPush = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+      expect(Object.keys(afterPush.files)).toContain("knowledge/agents/brief.md");
+
+      vi.mocked(deleteRemoteFile).mockClear();
+      const walked = await share({
+        paths: [companyRoot],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        propagateDeletes: true,
+        propagateDeletePolicy: "all",
+      });
+
+      expect(walked.filesDeleted).toBe(0);
+      const deletedKeys = vi.mocked(deleteRemoteFile).mock.calls.map((c) => c[1] as string);
+      expect(deletedKeys).not.toContain("knowledge/agents/brief.md");
+      const afterWalk = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+      expect(Object.keys(afterWalk.files)).toContain("knowledge/agents/brief.md");
+    });
+  });
+
   // ── Bulk-asymmetry circuit-breaker ─────────────────────────────────────
   //
   // Defends against the "local mirror lost, journal still full" failure
@@ -5646,6 +6413,7 @@ describe("currency-gated: journal version 2 fixtures", () => {
   });
 });
 
+
 describe("scope-invalid key hardening on push (doubled companies/ tree — incident 2026-07-11)", () => {
   let tmpDir: string;
   let stateDir: string;
@@ -5782,3 +6550,27 @@ describe("scope-invalid key hardening on push (doubled companies/ tree — incid
     expect(events.filter((e) => e.type === "skip-invalid-scoped-key")).toEqual([]);
   });
 });
+
+// ── Pure-function unit coverage: isForbiddenCompanyVaultKey ───────────────────
+//
+// Contract: in a COMPANY vault (personalMode=false) any key under `companies/`
+// is a doubly-scoped corrupt object and must be refused; in a PERSONAL vault
+// (personalMode=true) `companies/` keys are legitimate and handled by the
+// dedicated personalMode branch, so this guard must NOT fire there.
+describe("isForbiddenCompanyVaultKey (company-vault double-scope contract)", () => {
+  it.each([
+    // Company vault: companies/* keys are corrupt → forbidden.
+    ["companies/frogbear/drafts/reports/signals-2026-06-15.html", false, true],
+    ["companies/acme/knowledge/readme.md", false, true],
+    ["companies/manifest.yaml", false, true],
+    // Company vault: bucket-relative keys are legitimate → allowed.
+    ["docs/handoff.md", false, false],
+    ["knowledge/readme.md", false, false],
+    // Personal vault: companies/* keys are NOT forbidden here (handled by the
+    // personalMode branch, which carries its own nuanced gating).
+    ["companies/frogbear/drafts/reports/signals-2026-06-15.html", true, false],
+    ["docs/handoff.md", true, false],
+  ])("key=%s personalMode=%s → forbidden=%s", (key, personalMode, expected) => {
+    expect(isForbiddenCompanyVaultKey(key, personalMode)).toBe(expected);
+  });
+});