@indigoai-us/hq-cloud 6.14.36 → 6.14.39

package/dist/cli/share.test.js

@@ -39,7 +39,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 { VaultAuthError } from "../vault-client.js";
 const mockConfig = {
@@ -47,6 +47,11 @@ const mockConfig = {
     authToken: "test-jwt-token",
     region: "us-east-1",
 };
+function errnoError(code) {
+    const err = new Error(`${code}: invalid argument, readlink`);
+    err.code = code;
+    return err;
+}
 /**
  * Build a pre-vended EntityContext as if a caller (e.g. AppBar) had already
  * called `/sts/vend-child` and is passing the result into share() via the
@@ -100,6 +105,175 @@ describe("wrapFilterWithIgnoreVisibility", () => {
         expect(noteworthy).toEqual(["companies/indigo/knowledge/repos/foo.md"]);
     });
 });
+describe("resolveNamedPath (feedback_258e4a86 / feedback_a51cb63d)", () => {
+    let tmpDir;
+    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;
+    let hqRoot;
+    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",
@@ -274,16 +448,34 @@ describe("share", () => {
         // Key is "knowledge/crawl.json", not "companies/acme/knowledge/crawl.json"
         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);
         expect(uploadFile).not.toHaveBeenCalled();
@@ -1434,6 +1626,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({
@@ -2079,6 +2272,101 @@ describe("share", () => {
         // not act on files outside the named scope.
         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 });
@@ -3280,6 +3568,81 @@ describe("share", () => {
             expect(uploadFile).toHaveBeenCalledWith(expect.anything(), realPolicy, "policies/real.md", undefined, expect.anything());
             expect(uploadSymlink).toHaveBeenCalledWith(expect.anything(), "real.md", "policies/link.md", undefined, expect.anything());
         });
+        it("skips and reports a top-level link whose win32 readlink raises EINVAL", () => {
+            const companyRoot = path.join(tmpDir, "companies", "acme");
+            const targetDir = path.join(tmpDir, "outside", "target");
+            fs.mkdirSync(targetDir, { recursive: true });
+            fs.writeFileSync(path.join(targetDir, "must-not-upload.md"), "private target bytes");
+            const unreadableLink = path.join(companyRoot, "knowledge");
+            fs.mkdirSync(companyRoot, { recursive: true });
+            fs.symlinkSync(targetDir, unreadableLink, "dir");
+            const realReadlinkSync = fs.readlinkSync;
+            const readlinkSpy = vi
+                .spyOn(fs, "readlinkSync")
+                .mockImplementation(((linkPath) => {
+                if (linkPath === unreadableLink)
+                    throw errnoError("EINVAL");
+                return realReadlinkSync(linkPath);
+            }));
+            const warnings = vi.spyOn(console, "error").mockImplementation(() => { });
+            const unreachable = [];
+            try {
+                const collected = shareTesting.collectFiles([unreadableLink], tmpDir, companyRoot, () => true, {
+                    onUnreachablePath: (namedPath, reason) => unreachable.push([namedPath, reason]),
+                });
+                expect(collected).toEqual([]);
+                expect(unreachable).toEqual([[unreadableLink, "unreadable-link"]]);
+            }
+            finally {
+                warnings.mockRestore();
+                readlinkSpy.mockRestore();
+            }
+        });
+        it("skips and names a nested unreadable link without descending into its target", async () => {
+            const companyRoot = path.join(tmpDir, "companies", "acme");
+            const policiesDir = path.join(companyRoot, "policies");
+            const targetDir = path.join(tmpDir, "outside", "target");
+            fs.mkdirSync(policiesDir, { recursive: true });
+            fs.mkdirSync(targetDir, { recursive: true });
+            fs.writeFileSync(path.join(policiesDir, "safe.md"), "safe bytes");
+            fs.writeFileSync(path.join(targetDir, "must-not-upload.md"), "private target bytes");
+            const unreadableLink = path.join(policiesDir, "unreadable-link");
+            fs.symlinkSync(targetDir, unreadableLink, "dir");
+            const realReadlinkSync = fs.readlinkSync;
+            const readlinkSpy = vi
+                .spyOn(fs, "readlinkSync")
+                .mockImplementation(((linkPath) => {
+                if (linkPath === unreadableLink)
+                    throw errnoError("EINVAL");
+                return realReadlinkSync(linkPath);
+            }));
+            const warnings = vi.spyOn(console, "error").mockImplementation(() => { });
+            const events = [];
+            try {
+                const result = await share({
+                    paths: [companyRoot],
+                    company: "acme",
+                    vaultConfig: mockConfig,
+                    hqRoot: tmpDir,
+                    onEvent: (event) => events.push(event),
+                });
+                expect(result.filesUploaded).toBe(1);
+                expect(result.unreachablePaths).toEqual(["policies/unreadable-link"]);
+                expect(uploadFile).toHaveBeenCalledWith(expect.anything(), path.join(policiesDir, "safe.md"), "policies/safe.md", undefined, expect.anything());
+                expect(uploadFile).not.toHaveBeenCalledWith(expect.anything(), path.join(unreadableLink, "must-not-upload.md"), "policies/unreadable-link/must-not-upload.md", undefined, expect.anything());
+                expect(uploadSymlink).not.toHaveBeenCalledWith(expect.anything(), expect.anything(), "policies/unreadable-link", undefined, expect.anything());
+                expect(events).toContainEqual({
+                    type: "not-shipped",
+                    reason: "unreadable-link",
+                    count: 1,
+                    samplePaths: ["policies/unreadable-link"],
+                });
+            }
+            finally {
+                warnings.mockRestore();
+                readlinkSpy.mockRestore();
+            }
+        });
         it("accepts a symlink inside the company folder even when its target lives outside", async () => {
             // Codex P2 follow-up: pre-fix, isWithin canonicalized the link
             // via realpathSync, so a directory symlink whose target lived
@@ -3419,6 +3782,337 @@ describe("share", () => {
             expect(calls.find((c) => c[2].includes("secret.md"))).toBeUndefined();
         });
     });
+    // ── 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 = [];
+            await expect(share({
+                paths: [stray, path.join(companyRoot, "in-scope.md")],
+                company: "acme",
+                vaultConfig: mockConfig,
+                hqRoot: tmpDir,
+                onEvent: (e) => events.push(e),
+            })).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;
+            try {
+                await share({
+                    paths: [stray],
+                    company: "acme",
+                    vaultConfig: mockConfig,
+                    hqRoot: tmpDir,
+                });
+            }
+            catch (e) {
+                err = e;
+            }
+            expect(err).toBeInstanceOf(UnreachablePushPathsError);
+            const unreachable = err;
+            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 = [];
+            const result = await share({
+                paths: [companyRoot],
+                company: "acme",
+                vaultConfig: mockConfig,
+                hqRoot: tmpDir,
+                onEvent: (e) => events.push(e),
+            });
+            // 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]);
+            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
@@ -4775,6 +5469,67 @@ describe("scope-invalid key hardening on push (doubled companies/ tree — incid
         const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
         expect(journal.files["companies/acme/knowledge/poison.md"]).toBeUndefined();
     });
+    it("defers an unreadable scope-invalid symlink tombstone without a fatal error", async () => {
+        const companyRoot = path.join(tmpDir, "companies", "acme");
+        const linkKey = "companies/acme/knowledge/unreadable-link";
+        const linkPath = path.join(companyRoot, ...linkKey.split("/"));
+        const targetDir = path.join(tmpDir, "outside", "target");
+        fs.mkdirSync(path.dirname(linkPath), { recursive: true });
+        fs.mkdirSync(targetDir, { recursive: true });
+        fs.symlinkSync(targetDir, linkPath, "dir");
+        const journalPath = path.join(stateDir, "sync-journal.acme.json");
+        fs.writeFileSync(journalPath, JSON.stringify({
+            version: "1",
+            lastSync: new Date().toISOString(),
+            files: {
+                [linkKey]: {
+                    hash: "recorded-link-hash",
+                    size: 0,
+                    syncedAt: new Date().toISOString(),
+                    direction: "up",
+                    remoteEtag: "poison-etag",
+                },
+            },
+        }));
+        const realReadlinkSync = fs.readlinkSync;
+        let linkReadCount = 0;
+        const readlinkSpy = vi
+            .spyOn(fs, "readlinkSync")
+            .mockImplementation(((candidate) => {
+            if (candidate === linkPath && ++linkReadCount === 2) {
+                throw errnoError("EINVAL");
+            }
+            return realReadlinkSync(candidate);
+        }));
+        const events = [];
+        try {
+            const result = await share({
+                paths: [companyRoot],
+                company: "acme",
+                vaultConfig: mockConfig,
+                hqRoot: tmpDir,
+                skipUnchanged: true,
+                propagateDeletes: true,
+                propagateDeletePolicy: "currency-gated",
+                onEvent: (event) => events.push(event),
+            });
+            expect(linkReadCount).toBe(2);
+            expect(result.filesTombstoned).toBe(0);
+            expect(fs.lstatSync(linkPath).isSymbolicLink()).toBe(true);
+            expect(events).toContainEqual({
+                type: "not-shipped",
+                reason: "unreadable-link",
+                count: 1,
+                samplePaths: [linkKey],
+            });
+            expect(events.some((event) => event.type === "error")).toBe(false);
+            const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+            expect(journal.files[linkKey]).toBeDefined();
+        }
+        finally {
+            readlinkSpy.mockRestore();
+        }
+    });
     it("personal-mode push still uploads companies/{slug}/ keys (local non-cloud companies are legitimate)", async () => {
         const localCo = path.join(tmpDir, "companies", "localco");
         fs.mkdirSync(localCo, { recursive: true });
@@ -4795,4 +5550,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);
+    });
+});
 //# sourceMappingURL=share.test.js.map