@indigoai-us/hq-cloud 6.2.4 → 6.2.6

package/dist/cli/watch-event-push-conflict.test.js

@@ -0,0 +1,210 @@
+/**
+ * Regression guard: the watch + event-push path must NOT mint phantom
+ * `.conflict-*` mirrors for an ordinary single-writer local edit.
+ *
+ * Background (feedback_ef2b7c8c): a user editing files under
+ * `companies/{slug}/` saw the menubar's watch/event-push runner mint a
+ * `.conflict-<ts>-<machine>` mirror on EVERY ordinary local Edit/Write —
+ * thousands of phantom files in a single session. The watch/event-push runner
+ * reacts to a local change by running a targeted `--direction push` pass, i.e.
+ * `share()` over the changed company subtree, so the conflict-minting logic is
+ * share()'s push-side conflict gate. The original gate flagged a conflict on
+ * `localChanged` alone (`journalEntry.hash !== localHash`), which fires for
+ * every edit of any already-synced file. The gate now requires
+ * `(localChanged && remoteChanged) || isFreshCollision`: a single writer never
+ * has `remoteChanged` (the live S3 ETag still equals the journal's recorded
+ * baseline), so an ordinary edit is uploaded, not mirrored.
+ *
+ * This test pins that contract end-to-end through `share()` using the same
+ * mocked-S3 harness as `share.test.ts`, modelling a single-writer remote whose
+ * ETag is always exactly what THIS device last uploaded. A positive control
+ * (a genuine out-of-band peer write) proves the guard is not trivially
+ * always-zero: real divergence is still detected.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { clearContextCache } from "../context.js";
+vi.mock("../s3.js", () => ({
+    toPosixKey: (key) => key.split("\\").join("/"),
+    uploadFile: vi.fn(),
+    uploadSymlink: vi.fn().mockResolvedValue({ etag: '"upload-symlink-etag"' }),
+    downloadFile: vi.fn().mockResolvedValue(undefined),
+    listRemoteFiles: vi.fn().mockResolvedValue([]),
+    deleteRemoteFile: vi.fn().mockResolvedValue(undefined),
+    headRemoteFile: vi.fn(),
+    primeObjectTransport: vi.fn().mockResolvedValue(undefined),
+    primeUploads: vi.fn().mockResolvedValue(undefined),
+}));
+vi.mock("readline", () => ({
+    createInterface: vi.fn(() => ({ question: vi.fn(), close: vi.fn() })),
+}));
+import { share } from "./share.js";
+import { downloadFile, headRemoteFile, uploadFile } from "../s3.js";
+const mockConfig = {
+    apiUrl: "https://vault-api.test",
+    authToken: "test-jwt-token",
+    region: "us-east-1",
+};
+const mockEntity = {
+    uid: "cmp_01ABCDEF",
+    slug: "acme",
+    bucketName: "hq-vault-acme-123",
+    status: "active",
+};
+function setupFetchMock() {
+    vi.stubGlobal("fetch", vi.fn().mockImplementation(async (url) => {
+        const u = String(url);
+        if (u.includes("/entity/check-slug/me"))
+            return {
+                ok: true,
+                status: 200,
+                json: async () => ({ available: false, conflictingCompanyUid: mockEntity.uid }),
+                text: async () => "",
+            };
+        if (u.includes("/entity/by-slug/") || /\/entity\/cmp_/.test(u))
+            return { ok: true, status: 200, json: async () => ({ entity: mockEntity }), text: async () => "" };
+        if (u.includes("/sts/vend"))
+            return {
+                ok: true,
+                status: 200,
+                json: async () => ({
+                    credentials: {
+                        accessKeyId: "ASIA_TEST",
+                        secretAccessKey: "s",
+                        sessionToken: "t",
+                        expiration: new Date(Date.now() + 9e5).toISOString(),
+                    },
+                    expiresAt: new Date(Date.now() + 9e5).toISOString(),
+                }),
+                text: async () => "",
+            };
+        return { ok: false, status: 404, text: async () => "Not found" };
+    }));
+}
+/** Every `.conflict-<ts>-*` mirror file anywhere under `root`. */
+function countConflictMirrors(root) {
+    const out = [];
+    const walk = (d) => {
+        for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+            const p = path.join(d, e.name);
+            if (e.isDirectory())
+                walk(p);
+            else if (/\.conflict-/.test(e.name))
+                out.push(p);
+        }
+    };
+    walk(root);
+    return out;
+}
+/**
+ * In-memory single-writer S3: the object's ETag is always exactly what THIS
+ * device last uploaded (no peer ever writes). `lastModified` advances on each
+ * PUT to model S3 stamping it server-side. The S3-module signatures are
+ * `uploadFile(ctx, localPath, key)`, `headRemoteFile(ctx, key)`,
+ * `downloadFile(ctx, key, dest)` — wire the mocks to match exactly.
+ */
+function wireSingleWriterRemote() {
+    const remote = new Map();
+    let clock = Date.now();
+    let seq = 0;
+    vi.mocked(uploadFile).mockImplementation(async (_ctx, localPath, key) => {
+        const etag = `"etag-${seq++}"`;
+        clock += 1000;
+        remote.set(key, { etag, lastModified: new Date(clock), size: fs.statSync(localPath).size });
+        return { etag };
+    });
+    vi.mocked(headRemoteFile).mockImplementation(async (_ctx, key) => {
+        const r = remote.get(key);
+        return r ? { lastModified: r.lastModified, etag: r.etag, size: r.size } : null;
+    });
+    vi.mocked(downloadFile).mockImplementation(async (_ctx, _key, dest) => {
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, "remote-bytes\n");
+        return {};
+    });
+    return remote;
+}
+describe("watch + event-push conflict regression (feedback_ef2b7c8c)", () => {
+    let tmpDir;
+    let stateDir;
+    beforeEach(() => {
+        clearContextCache();
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watch-conflict-"));
+        stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watch-state-"));
+        process.env.HQ_STATE_DIR = stateDir;
+        setupFetchMock();
+    });
+    afterEach(() => {
+        vi.unstubAllGlobals();
+        vi.clearAllMocks();
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+        fs.rmSync(stateDir, { recursive: true, force: true });
+        delete process.env.HQ_STATE_DIR;
+    });
+    it("a single writer's repeated local edits mint ZERO .conflict-* files", async () => {
+        const companyRoot = path.join(tmpDir, "companies", "acme");
+        fs.mkdirSync(companyRoot, { recursive: true });
+        const files = ["notes.md", "plan.md", "ideas.md"].map((n) => path.join(companyRoot, n));
+        for (const f of files)
+            fs.writeFileSync(f, "v0\n");
+        wireSingleWriterRemote();
+        const conflictPathsSeen = [];
+        // The event-push runner pushes the changed company subtree. Mirror that:
+        // share() over the company root on every settled change.
+        const eventPush = async () => {
+            const r = await share({
+                paths: [companyRoot],
+                company: "acme",
+                vaultConfig: mockConfig,
+                hqRoot: tmpDir,
+                onConflict: "keep",
+                onEvent: () => { },
+            });
+            conflictPathsSeen.push(...r.conflictPaths);
+        };
+        // Initial sync establishes the journal baseline (first upload of each file).
+        await eventPush();
+        // An editing session: 30 ordinary local edits, round-robin across the
+        // files, each followed by its targeted event-push.
+        for (let i = 0; i < 30; i++) {
+            fs.writeFileSync(files[i % files.length], `v${i + 1}\n`);
+            await eventPush();
+        }
+        expect(countConflictMirrors(tmpDir)).toEqual([]);
+        expect(conflictPathsSeen).toEqual([]);
+    });
+    it("positive control: a genuine peer write is still detected as a conflict", async () => {
+        const companyRoot = path.join(tmpDir, "companies", "acme");
+        fs.mkdirSync(companyRoot, { recursive: true });
+        const file = path.join(companyRoot, "contested.md");
+        fs.writeFileSync(file, "v0\n");
+        const remote = wireSingleWriterRemote();
+        const conflictPathsSeen = [];
+        const eventPush = async () => {
+            const r = await share({
+                paths: [companyRoot],
+                company: "acme",
+                vaultConfig: mockConfig,
+                hqRoot: tmpDir,
+                onConflict: "keep",
+                onEvent: () => { },
+            });
+            conflictPathsSeen.push(...r.conflictPaths);
+        };
+        await eventPush(); // baseline
+        // A peer advances the remote object out-of-band to DIFFERENT bytes. Journal
+        // keys are company-relative, so the key is "contested.md".
+        remote.set("contested.md", { etag: '"peer-etag"', lastModified: new Date(Date.now() + 60_000), size: 99 });
+        // ...and we also edit locally → both sides moved → a genuine conflict.
+        fs.writeFileSync(file, "v1-local\n");
+        await eventPush();
+        // Existing-entry push conflicts surface via conflictPaths (the inspection
+        // mirror is written by the pull leg). The contract under test: a REAL
+        // divergence is still flagged — the single-writer guard above did not
+        // over-correct into swallowing true conflicts.
+        expect(conflictPathsSeen).toContain("contested.md");
+    });
+});
+//# sourceMappingURL=watch-event-push-conflict.test.js.map

package/dist/cli/watch-event-push-conflict.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-event-push-conflict.test.js","sourceRoot":"","sources":["../../src/cli/watch-event-push-conflict.test.ts"],"names":[],"mappings":"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"}

package/dist/prefix-coalesce.d.ts

@@ -35,6 +35,28 @@ export declare function coalescePrefixes(prefixes: readonly string[]): string[];
  * `startsWith` semantics as `coalescePrefixes`.
  */
 export declare function isCoveredByAny(path: string, prefixSet: readonly string[]): boolean;
+/**
+ * Directory companion to `isCoveredByAny`: should the push/pull walk DESCEND
+ * into directory `relDir` (company-relative, no leading slash) given the
+ * granted `prefixSet`?
+ *
+ * A file uses plain `startsWith` (`isCoveredByAny`), but a directory must be
+ * descended whenever it COULD contain an in-scope file — which is true in two
+ * directions:
+ *   - the directory sits INSIDE a granted prefix (`knowledge/sub` under
+ *     `knowledge/`), or
+ *   - a granted prefix sits INSIDE the directory (`knowledge/` under the
+ *     company root `""`, or `knowledge/README.md` under `knowledge/`).
+ * Without the second case the walk would refuse to descend into `knowledge/`
+ * to reach a `knowledge/README.md` exact-file grant, scoping the whole tree
+ * to nothing.
+ *
+ * The directory is normalized to a trailing-slash form so the `startsWith`
+ * comparisons line up with coalesced prefixes (which are themselves either
+ * trailing-slash dir prefixes or exact-file keys). The empty string (company
+ * root) always descends when any prefix exists.
+ */
+export declare function isDirInScope(relDir: string, prefixSet: readonly string[]): boolean;
 /**
  * Normalize a raw ACL grant `path` into a COMPANY-RELATIVE prefix suitable
  * for `coalescePrefixes` + `isCoveredByAny` (which do literal `startsWith`

package/dist/prefix-coalesce.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prefix-coalesce.d.ts","sourceRoot":"","sources":["../src/prefix-coalesce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAyBtE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAKT;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAezE"}
+{"version":3,"file":"prefix-coalesce.d.ts","sourceRoot":"","sources":["../src/prefix-coalesce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAyBtE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAKT;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAST;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAezE"}

package/dist/prefix-coalesce.js

@@ -66,6 +66,41 @@ export function isCoveredByAny(path, prefixSet) {
     }
     return false;
 }
+/**
+ * Directory companion to `isCoveredByAny`: should the push/pull walk DESCEND
+ * into directory `relDir` (company-relative, no leading slash) given the
+ * granted `prefixSet`?
+ *
+ * A file uses plain `startsWith` (`isCoveredByAny`), but a directory must be
+ * descended whenever it COULD contain an in-scope file — which is true in two
+ * directions:
+ *   - the directory sits INSIDE a granted prefix (`knowledge/sub` under
+ *     `knowledge/`), or
+ *   - a granted prefix sits INSIDE the directory (`knowledge/` under the
+ *     company root `""`, or `knowledge/README.md` under `knowledge/`).
+ * Without the second case the walk would refuse to descend into `knowledge/`
+ * to reach a `knowledge/README.md` exact-file grant, scoping the whole tree
+ * to nothing.
+ *
+ * The directory is normalized to a trailing-slash form so the `startsWith`
+ * comparisons line up with coalesced prefixes (which are themselves either
+ * trailing-slash dir prefixes or exact-file keys). The empty string (company
+ * root) always descends when any prefix exists.
+ */
+export function isDirInScope(relDir, prefixSet) {
+    const dir = relDir === "" || relDir.endsWith("/") ? relDir : relDir + "/";
+    for (const p of prefixSet) {
+        if (p === "")
+            return true; // full scope
+        if (dir === "")
+            return true; // company root — descend to reach grants
+        if (dir.startsWith(p))
+            return true; // dir is inside a granted prefix
+        if (p.startsWith(dir))
+            return true; // a granted prefix is inside dir
+    }
+    return false;
+}
 /**
  * Normalize a raw ACL grant `path` into a COMPANY-RELATIVE prefix suitable
  * for `coalescePrefixes` + `isCoveredByAny` (which do literal `startsWith`

package/dist/prefix-coalesce.js.map

@@ -1 +1 @@
-{"version":3,"file":"prefix-coalesce.js","sourceRoot":"","sources":["../src/prefix-coalesce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,MAAM,UAAU,gBAAgB,CAAC,QAA2B;IAC1D,wBAAwB;IACxB,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;IACjC,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC;YACtC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAChB,CAAC;IACH,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEjC,uEAAuE;IACvE,0EAA0E;IAC1E,oBAAoB;IACpB,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;IAClC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,QAAQ,GAAkB,IAAI,CAAC;IACnC,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,QAAQ,KAAK,IAAI,IAAI,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAChD,uCAAuC;YACvC,SAAS;QACX,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACf,QAAQ,GAAG,CAAC,CAAC;IACf,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAY,EACZ,SAA4B;IAE5B,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,IAAI,CAAC,KAAK,EAAE,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;IAClD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAiB,EAAE,IAAY;IAC/D,IAAI,CAAC,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC9C,2CAA2C;IAC3C,MAAM,aAAa,GAAG,aAAa,IAAI,GAAG,CAAC;IAC3C,MAAM,UAAU,GAAG,GAAG,IAAI,GAAG,CAAC;IAC9B,IAAI,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QAChC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;SAAM,IAAI,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QACpC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IACD,wDAAwD;IACxD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,CAAC,CAAC,oCAAoC;IAC1E,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,mBAAmB;IAChE,IAAI,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,kBAAkB;IAC9D,OAAO,CAAC,CAAC,CAAC,iEAAiE;AAC7E,CAAC"}
+{"version":3,"file":"prefix-coalesce.js","sourceRoot":"","sources":["../src/prefix-coalesce.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cloud",
-  "version": "6.2.4",
+  "version": "6.2.6",
   "description": "HQ by Indigo cloud sync engine \u2014 bidirectional S3 sync for mobile access",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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

@@ -120,6 +120,7 @@ function defaultShareResult(overrides: Partial<ShareResult> = {}): ShareResult {
     filesRefusedStale: 0,
     filesRefusedStalePaths: [],
     filesExcludedByPolicy: 0,
+    filesExcludedByScope: 0,
     conflictPaths: [],
     aborted: false,
     ...overrides,
@@ -1781,6 +1782,44 @@ describe("--direction", () => {
     expect(opts.paths).toEqual(["/tmp/fake-hq/companies/acme"]);
     expect(opts.company).toBe("cmp_a");
     expect(opts.hqRoot).toBe("/tmp/fake-hq");
+    // Owner / `all` scope (no membership sync-config) → NO prefixSet forwarded,
+    // preserving the pre-fix company-target args shape (full access).
+    expect(opts.prefixSet).toBeUndefined();
+  });
+
+  it("direction=push (shared membership): forwards the resolved ACL prefixSet to share() (feedback_ded09d56)", async () => {
+    // Plumbing regression for the fresh fix: a member/guest's push must be
+    // scoped to their granted prefixes so out-of-scope keys are filtered
+    // instead of drawing the server's 403 and aborting the whole company.
+    const shareSpy = vi.fn().mockResolvedValue(defaultShareResult());
+    const client = {
+      ...makeVaultStub({
+        memberships: [{ companyUid: "cmp_a" }],
+        entityGet: (uid: string) =>
+          Promise.resolve({ uid, slug: "acme" } as unknown as EntityInfo),
+      }),
+      getMembershipSyncConfig: async () => ({
+        membershipId: "mk_a",
+        syncMode: "shared",
+        isDefault: false,
+      }),
+      listMyExplicitGrants: async () => [
+        { companyUid: "cmp_a", path: "knowledge/", permission: "read", source: "person" },
+        { companyUid: "cmp_a", path: "policies/", permission: "read", source: "group" },
+      ],
+    } as unknown as ReturnType<typeof makeVaultStub>;
+    const deps = makeDeps({
+      createVaultClient: () => client,
+      sync: vi.fn(),
+      share: shareSpy,
+    });
+
+    await runRunner(
+      ["--companies", "--direction", "push", "--hq-root", "/tmp/fake-hq"],
+      deps,
+    );
+    const opts = (shareSpy.mock.calls[0] as [ShareOptions])[0];
+    expect(opts.prefixSet).toEqual(["knowledge/", "policies/"]);
   });
 
   it("direction=both: all-complete sums uploaded and downloaded across companies", async () => {

package/src/bin/sync-runner.ts

@@ -274,6 +274,7 @@ export type RunnerEvent =
   | ({ type: "error"; company?: string } & Omit<Extract<SyncProgressEvent, { type: "error" }>, "type">)
   | ({ type: "conflict"; company: string } & Omit<Extract<SyncProgressEvent, { type: "conflict" }>, "type">)
   | { type: "new-files"; company: string; files: Array<{ path: string; bytes: number; addedBy: string | null }> }
+  | { type: "scope-excluded"; company: string; count: number; samplePaths: string[] }
   | ({
       type: "complete";
       company: string;
@@ -1243,6 +1244,16 @@ export async function runRunner(
           company: companyLabel,
           files: event.files,
         });
+      } else if (event.type === "scope-excluded") {
+        // Push-side ACL scope exclusions — surface the named paths tagged to
+        // this company so the menubar/CLI can show "N skipped, outside your
+        // access" instead of the file silently never uploading.
+        emit({
+          type: "scope-excluded",
+          company: companyLabel,
+          count: event.count,
+          samplePaths: event.samplePaths,
+        });
       }
     };
 
@@ -1256,6 +1267,7 @@ export async function runRunner(
         filesRefusedStale: 0,
         filesRefusedStalePaths: [],
         filesExcludedByPolicy: 0,
+        filesExcludedByScope: 0,
         conflictPaths: [],
         aborted: false,
       };
@@ -1307,6 +1319,26 @@ export async function runRunner(
           .map((p) => p.slug),
       );
 
+      // Resolve the membership's effective ACL scope ONCE so BOTH the push and
+      // pull legs respect the granted prefixes. The vault vends a child
+      // credential scoped to these prefixes; without filtering the PUSH plan to
+      // them, share() would HEAD/PUT keys outside the grant and the server's
+      // correct 403 (SCOPE_EXCEEDS_PARENT) would abort the WHOLE company with a
+      // generic error + exit 2. Personal-vault legs have no membership
+      // sync-config — they stay full-scope ("all"). Degrades to "all" on any
+      // error (a transient failure must never silently filter/prune the tree).
+      // Hoisted above the push block (it used to be resolved only for pull) so
+      // push gets the same scope; the pull leg below reuses this value.
+      const scope: PullScope =
+        target.personalMode === true
+          ? { syncMode: "all" }
+          : await resolvePullScope(
+              client,
+              target.uid,
+              target.slug,
+              parsed.hqRoot,
+            );
+
       if (doPush) {
         activePhase = "push";
         // For the personal slot we hand share() both (a) the top-level
@@ -1365,6 +1397,13 @@ export async function runRunner(
           ...(decommissionPrefixes && decommissionPrefixes.length > 0
             ? { decommissionPrefixes }
             : {}),
+          // US-005 symmetry: scope the PUSH plan to the membership's granted
+          // ACL prefixes so out-of-scope keys are skipped (and surfaced via a
+          // `scope-excluded` event) instead of drawing the server's 403 and
+          // aborting the company. `undefined` for `syncMode: "all"` (owner /
+          // personal) → no scope filter, identical to the pre-fix shape so the
+          // "company-target args" contract test stays green.
+          ...(scope.prefixSet !== undefined ? { prefixSet: scope.prefixSet } : {}),
         });
       }
 
@@ -1373,20 +1412,11 @@ export async function runRunner(
       // whichever side `--on-conflict abort` just protected.
       if (doPull && !pushResult.aborted) {
         activePhase = "pull";
-        // US-005: resolve the membership's effective download scope so the
-        // pull only materializes in-scope keys (and prunes clean orphans when
-        // scope shrank). Personal-vault legs have no membership sync-config —
-        // they stay full-scope (`all`). Degrades to `all` on any error so a
-        // transient failure can't silently prune the tree.
-        const pullScope: PullScope =
-          target.personalMode === true
-            ? { syncMode: "all" }
-            : await resolvePullScope(
-                client,
-                target.uid,
-                target.slug,
-                parsed.hqRoot,
-              );
+        // US-005: the pull only materializes in-scope keys (and prunes clean
+        // orphans when scope shrank). Reuse the `scope` resolved once above so
+        // push and pull apply the SAME granted prefixes and we avoid a second
+        // `listMyExplicitGrants` round-trip per company.
+        const pullScope: PullScope = scope;
         pullResult = await syncFn({
           company: target.uid,
           vaultConfig,

package/src/cli/share.test.ts

@@ -586,6 +586,114 @@ describe("share", () => {
     expect(fs.readFileSync(testFile, "utf-8")).toBe("my-local-version");
   });
 
+  it("scoped push (plan-exceeds-grant): syncs the in-scope subset, skips out-of-scope paths, never aborts (feedback_ded09d56)", async () => {
+    // Real case (look-optic): a FILE_ACL grant covered {knowledge,policies,
+    // workers}/* + company.yaml, but the upload plan also contained
+    // settings/.gitkeep + projects/.gitkeep. Pre-fix, the push walked the
+    // whole company tree, HEAD'd an out-of-scope key, the scoped child
+    // credential drew a 403 SCOPE_EXCEEDS_PARENT, and the runner aborted the
+    // ENTIRE company (exit 2) naming no path. The fix scopes the push plan to
+    // the granted prefixSet (symmetric with the pull-side skip-out-of-scope):
+    // in-scope files upload, out-of-scope paths are skipped + surfaced via a
+    // `scope-excluded` event, and the company completes.
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(path.join(companyRoot, "knowledge"), { recursive: true });
+    fs.mkdirSync(path.join(companyRoot, "policies"), { recursive: true });
+    fs.mkdirSync(path.join(companyRoot, "settings"), { recursive: true });
+    fs.mkdirSync(path.join(companyRoot, "projects"), { recursive: true });
+    fs.writeFileSync(path.join(companyRoot, "company.yaml"), "name: Acme\n");
+    fs.writeFileSync(path.join(companyRoot, "knowledge", "readme.md"), "# kb\n");
+    fs.writeFileSync(path.join(companyRoot, "policies", "p.md"), "policy\n");
+    fs.writeFileSync(path.join(companyRoot, "settings", ".gitkeep"), "");
+    fs.writeFileSync(path.join(companyRoot, "projects", ".gitkeep"), "");
+
+    // No remote anywhere → every in-scope file is a clean upload.
+    vi.mocked(headRemoteFile).mockResolvedValue(null);
+
+    const events: Array<{ type?: string; path?: string; count?: number; samplePaths?: string[] }> = [];
+    const result = await share({
+      paths: [companyRoot],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      // Coalesced company-relative grant prefixes (what resolvePullScope hands
+      // the runner for a shared membership).
+      prefixSet: ["company.yaml", "knowledge/", "policies/", "workers/"],
+      onEvent: (e) => events.push(e as { type?: string }),
+    });
+
+    // In-scope subset uploaded; out-of-scope never PUT. (company.yaml is in
+    // the grant but is independently dropped by the base ignore filter — it's
+    // in DEFAULT_IGNORES — so it never uploads regardless of scope; the scope
+    // filter layers on top of the ignore filter, not under it.)
+    const uploadedPaths = events
+      .filter((e) => e.type === "progress")
+      .map((e) => e.path)
+      .sort();
+    expect(uploadedPaths).toEqual(["knowledge/readme.md", "policies/p.md"]);
+    expect(result.filesUploaded).toBe(2);
+    // The two out-of-scope directories were excluded and named.
+    expect(result.filesExcludedByScope).toBe(2);
+    const scopeEv = events.find((e) => e.type === "scope-excluded") as
+      | { count: number; samplePaths: string[] }
+      | undefined;
+    expect(scopeEv).toBeDefined();
+    expect(scopeEv!.count).toBe(2);
+    expect(scopeEv!.samplePaths.sort()).toEqual(["projects/", "settings/"]);
+    // No conflict, no error — the company completed cleanly (no abort).
+    expect(result.aborted).toBe(false);
+    expect(events.some((e) => e.type === "error")).toBe(false);
+    // uploadFile was never called for an out-of-scope key.
+    const putKeys = vi.mocked(uploadFile).mock.calls.map((c) => c[2]);
+    expect(putKeys).not.toContain("settings/.gitkeep");
+    expect(putKeys).not.toContain("projects/.gitkeep");
+  });
+
+  it("scoped push defense-in-depth: a 403 on HEAD skips that key (named error) instead of aborting the company", async () => {
+    // Belt-and-suspenders: even if a key slips past the prefix filter (a grant
+    // that changed mid-run, a pin outside the grant, prefix-coalesce
+    // imprecision), the server's correct 403 on the HEAD must NOT abort the
+    // whole company. Pre-fix the HEAD sat outside the per-file PUT try/catch,
+    // so the throw bubbled to workerErrors -> `throw first` -> exit 2.
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const okFile = path.join(companyRoot, "in-scope.md");
+    const blockedFile = path.join(companyRoot, "out-of-reach.md");
+    fs.writeFileSync(okFile, "ok\n");
+    fs.writeFileSync(blockedFile, "denied\n");
+
+    // The scoped credential 403s on the out-of-scope key's HEAD; the other
+    // key heads cleanly (no remote).
+    vi.mocked(headRemoteFile).mockImplementation(async (_ctx, key) => {
+      if (key === "out-of-reach.md") {
+        const err = new Error("access denied");
+        (err as { name: string }).name = "AccessDenied";
+        throw err;
+      }
+      return null;
+    });
+
+    const events: Array<{ type?: string; path?: string; message?: string }> = [];
+    const result = await share({
+      paths: [okFile, blockedFile],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      onEvent: (e) => events.push(e as { type?: string }),
+    });
+
+    // Company did NOT abort; the in-scope file still uploaded.
+    expect(result.aborted).toBe(false);
+    expect(result.filesUploaded).toBe(1);
+    const putKeys = vi.mocked(uploadFile).mock.calls.map((c) => c[2]);
+    expect(putKeys).toEqual(["in-scope.md"]);
+    // The blocked key surfaced as a path-named, scope-clear error event.
+    const errs = events.filter((e) => e.type === "error") as Array<{ path?: string; message?: string }>;
+    expect(errs).toHaveLength(1);
+    expect(errs[0].path).toBe("out-of-reach.md");
+    expect(errs[0].message).toMatch(/outside granted ACL scope/i);
+  });
+
   it("uploads (no conflict) when only the local side changed since last sync", async () => {
     // Regression for hq-cloud#<conflict-detection>: a local edit to a file
     // that exists on S3 used to trigger a push conflict because the
@@ -810,6 +918,7 @@ describe("share", () => {
           e.type === "plan" ||
           e.type === "new-files" ||
           e.type === "personal-vault-out-of-policy" ||
+          e.type === "scope-excluded" ||
           e.type === "delete-refused-bulk-asymmetry"
         ) return;
         events.push({