@indigoai-us/hq-cloud 6.2.5 → 6.2.7

package/src/bin/sync-runner.ts

@@ -210,16 +210,35 @@ export function resolveSkipPersonal(flag: boolean): boolean {
   return env === "1" || env === "true" || env === "yes";
 }
 
+/**
+ * Email domains enrolled in the presigned-URL transport rollout.
+ *
+ * Staged by the operator (2026-06-10) in descending user count: getindigo.ai
+ * was the pilot; gmail.com / vyg.ai / amass.com are batch 2. The presign
+ * transport also routes every upload through the vault API's
+ * `validateObjectKey` (INVALID_KEY_BACKSLASH et al.), so enrolling a domain
+ * upgrades its server-side input validation versus the STS-direct path.
+ * Matching is on the EXACT domain (the part after the last `@`), not a
+ * suffix — `evil-gmail.com` and `gmail.com.evil.com` never match.
+ */
+const PRESIGN_ROLLOUT_DOMAINS: ReadonlySet<string> = new Set([
+  "getindigo.ai",
+  "gmail.com",
+  "vyg.ai",
+  "amass.com",
+]);
+
 /**
  * Decide whether this session uses the presigned-URL transport.
  *
- * Rollout gate: ON for accounts whose verified email is `@getindigo.ai`.
- * `HQ_SYNC_PRESIGN_TRANSPORT` overrides the email check in both directions
- * (`1`/`true`/`yes`/`on` → force on, `0`/`false`/`no`/`off` → force off) so
- * the transport can be exercised by non-getindigo testers or rolled back for
- * getindigo accounts without a redeploy. An unset/blank override falls through
- * to the email check; an unrecognized override value is ignored (email check
- * wins) rather than silently forcing a state.
+ * Rollout gate: ON for accounts whose verified email domain is enrolled in
+ * `PRESIGN_ROLLOUT_DOMAINS`. `HQ_SYNC_PRESIGN_TRANSPORT` overrides the email
+ * check in both directions (`1`/`true`/`yes`/`on` → force on,
+ * `0`/`false`/`no`/`off` → force off) so the transport can be exercised by
+ * unenrolled testers or rolled back for enrolled accounts without a redeploy.
+ * An unset/blank override falls through to the email check; an unrecognized
+ * override value is ignored (email check wins) rather than silently forcing
+ * a state.
  */
 export function resolvePresignTransport(
   email: string | undefined,
@@ -228,7 +247,10 @@ export function resolvePresignTransport(
   const o = (override ?? "").trim().toLowerCase();
   if (o === "1" || o === "true" || o === "yes" || o === "on") return true;
   if (o === "0" || o === "false" || o === "no" || o === "off") return false;
-  return typeof email === "string" && email.toLowerCase().endsWith("@getindigo.ai");
+  if (typeof email !== "string") return false;
+  const at = email.lastIndexOf("@");
+  if (at < 0) return false;
+  return PRESIGN_ROLLOUT_DOMAINS.has(email.slice(at + 1).toLowerCase());
 }
 
 // Personal-vault scope (exclusion list + path computer) lives in
@@ -274,6 +296,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 +1266,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 +1289,7 @@ export async function runRunner(
         filesRefusedStale: 0,
         filesRefusedStalePaths: [],
         filesExcludedByPolicy: 0,
+        filesExcludedByScope: 0,
         conflictPaths: [],
         aborted: false,
       };
@@ -1307,6 +1341,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 +1419,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 +1434,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({

package/src/cli/share.ts

@@ -41,6 +41,7 @@ import {
 import { resolveConflict } from "./conflict.js";
 import type { ConflictStrategy } from "./conflict.js";
 import type { SyncProgressEvent } from "./sync.js";
+import { isCoveredByAny, isDirInScope } from "../prefix-coalesce.js";
 import {
   buildConflictId,
   buildConflictPath,
@@ -591,6 +592,20 @@ export interface ShareOptions {
    * `sync-journal.personal.json` file.
    */
   journalSlug?: string;
+  /**
+   * Effective ACL push scope as a list of company-relative prefixes (the same
+   * coalesced `prefixSet` the pull leg uses for `syncMode: "shared"`). When
+   * provided, the upload + delete plans are filtered to paths covered by these
+   * prefixes — any candidate outside them is skipped (and surfaced via a
+   * `scope-excluded` event) rather than PUT, because the vended child
+   * credential is scoped to exactly these prefixes and an out-of-scope PUT
+   * draws the server's correct 403 `SCOPE_EXCEEDS_PARENT`.
+   *
+   * `undefined` (the owner/`all` case, and `hq share <file>`) applies NO scope
+   * filter — full access. An empty array means "no granted prefixes" → every
+   * path is out of scope (mirrors the pull side's `isCoveredByAny([])`).
+   */
+  prefixSet?: string[];
 }
 
 export interface ShareResult {
@@ -644,6 +659,16 @@ export interface ShareResult {
    * emitted exactly once if this is > 0).
    */
   filesExcludedByPolicy: number;
+  /**
+   * Number of distinct company-relative paths/prefixes skipped because they
+   * fell OUTSIDE the run's ACL `prefixSet` (member/guest scoped push). Always
+   * 0 when `prefixSet` is undefined (owner/`all`) or the whole tree is in
+   * scope. Mirrors the `count` field of the `scope-excluded` event (emitted
+   * once if this is > 0). These paths were never PUT, so the server's correct
+   * 403 `SCOPE_EXCEEDS_PARENT` is never triggered and the company still syncs
+   * its in-scope subset.
+   */
+  filesExcludedByScope: number;
   /**
    * Paths (company-relative) that were detected as push conflicts. Mirrors
    * `SyncResult.conflictPaths` so push and pull surface conflicts the same
@@ -653,6 +678,56 @@ export interface ShareResult {
   aborted: boolean;
 }
 
+/**
+ * Is this error the S3/STS "access denied" class? Expected when a scoped
+ * member/guest credential touches a key outside its granted ACL prefixes
+ * (the server's `SCOPE_EXCEEDS_PARENT` surfaces as a 403 AccessDenied /
+ * Forbidden). Mirrors the pull-side `isAccessDenied` in sync.ts so the push
+ * leg can treat a stray out-of-scope key as a skip rather than a fatal throw.
+ */
+function isAccessDenied(err: unknown): boolean {
+  if (err && typeof err === "object" && "name" in err) {
+    const name = (err as { name?: unknown }).name;
+    return name === "AccessDenied" || name === "Forbidden";
+  }
+  return false;
+}
+
+/**
+ * Wrap an existing path filter (ignore filter, optionally already wrapped with
+ * the personal-vault defaults) so that paths OUTSIDE the run's ACL `prefixSet`
+ * are rejected before they enter the upload OR delete plan. Keeps the
+ * `(absolutePath, isDir) => boolean` shape the rest of share() already uses
+ * (collectFiles / walkDir / computeDeletePlan), so wiring is one line at the
+ * filter-construction site — exactly like `wrapFilterWithPersonalVaultDefaults`.
+ *
+ * Files use `isCoveredByAny` (plain `startsWith`); directories use
+ * `isDirInScope` (descend if the dir is inside a grant OR a grant is inside
+ * the dir) so the walk still reaches deep/exact-file grants. Rejected entries
+ * are tagged via `onScopeExcluded` (directories with a trailing slash) so the
+ * runner can emit a single `scope-excluded` summary naming what was skipped.
+ */
+function wrapFilterWithScope(
+  underlying: (absPath: string, isDir?: boolean) => boolean,
+  syncRoot: string,
+  prefixSet: readonly string[],
+  onScopeExcluded: (rel: string) => void,
+): (absPath: string, isDir?: boolean) => boolean {
+  return (absPath: string, isDir?: boolean) => {
+    if (!underlying(absPath, isDir)) return false;
+    const rel = path.relative(syncRoot, absPath).split(path.sep).join("/");
+    if (rel === "" || rel.startsWith("..")) return true; // root / outside — defer
+    if (isDir) {
+      if (isDirInScope(rel, prefixSet)) return true;
+      onScopeExcluded(rel.endsWith("/") ? rel : rel + "/");
+      return false;
+    }
+    if (isCoveredByAny(rel, prefixSet)) return true;
+    onScopeExcluded(rel);
+    return false;
+  };
+}
+
 /**
  * Share local file(s) to the entity vault.
  */
@@ -768,9 +843,22 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     excludedSet.add(rel);
     excludedById[match.id] = (excludedById[match.id] ?? 0) + 1;
   };
-  const shouldSync = options.personalMode === true
+  // ACL scope filter (member/guest scoped push). The vended child credential
+  // is scoped to `options.prefixSet`; any candidate outside those prefixes
+  // would draw the server's correct 403 SCOPE_EXCEEDS_PARENT on PUT and abort
+  // the whole company. Pre-filter the plan to the granted subset instead —
+  // the push-side analogue of the pull leg's `skip-out-of-scope` (US-005).
+  // `undefined` = owner/`all` → no scope filter (full access).
+  const scopeExcludedSet = new Set<string>();
+  const onScopeExcluded = (rel: string) => {
+    scopeExcludedSet.add(rel);
+  };
+  const baseFilter = options.personalMode === true
     ? wrapFilterWithPersonalVaultDefaults(ignoreFilter, syncRoot, onExcluded)
     : ignoreFilter;
+  const shouldSync = options.prefixSet !== undefined
+    ? wrapFilterWithScope(baseFilter, syncRoot, options.prefixSet, onScopeExcluded)
+    : baseFilter;
   const journalSlug = options.journalSlug ?? ctx.slug;
   // Seed the canonical personal-vault journal from the legacy `personal` file
   // exactly once — engine-side so every consumer (sync-runner, hq-cli) gets
@@ -1008,7 +1096,32 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     // single-part etag) and compare. Match → no conflict, silently skip
     // the PUT (the bytes are already there). Mismatch → treat as a
     // conflict in the same shared branch below.
-    const remoteMeta = await headRemoteFile(ctx, relativePath);
+    // Defense-in-depth for the scoped-push 403: the `prefixSet` filter above
+    // should already have dropped any out-of-scope key from the plan, but a
+    // grant that changed mid-run, a pinned prefix outside the grant, or
+    // prefix-coalesce imprecision can still leave an out-of-scope key here.
+    // This HEAD sits OUTSIDE the per-file PUT try/catch below, so a thrown
+    // 403 used to bubble to `workerErrors` and abort the ENTIRE company with
+    // a generic message and exit 2. Catch the access-denied class, surface
+    // the offending PATH clearly, and skip just this key — the rest of the
+    // company still syncs. Non-access-denied errors re-throw unchanged.
+    let remoteMeta: Awaited<ReturnType<typeof headRemoteFile>>;
+    try {
+      remoteMeta = await headRemoteFile(ctx, relativePath);
+    } catch (headErr) {
+      if (isAccessDenied(headErr)) {
+        emit({
+          type: "error",
+          path: relativePath,
+          message:
+            "skipped: outside granted ACL scope (server returned 403 " +
+            "SCOPE_EXCEEDS_PARENT / access denied on HEAD). Grant this path " +
+            "to push it, or it stays local-only.",
+        });
+        return;
+      }
+      throw headErr;
+    }
     if (remoteMeta) {
       const journalEntry = journal.files[relativePath];
       const localChanged = !!journalEntry && journalEntry.hash !== localHash;
@@ -1214,7 +1327,13 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
       emit({
         type: "error",
         path: relativePath,
-        message: err instanceof Error ? err.message : String(err),
+        message: isAccessDenied(err)
+          ? "skipped: outside granted ACL scope (server returned 403 " +
+            "SCOPE_EXCEEDS_PARENT / access denied on PUT). Grant this path " +
+            "to push it, or it stays local-only."
+          : err instanceof Error
+            ? err.message
+            : String(err),
       });
     }
   };
@@ -1284,6 +1403,9 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
       // abort (matches the existing convention: abort short-circuits
       // before the end-of-run telemetry emits).
       filesExcludedByPolicy: excludedSet.size,
+      // Scope exclusions are likewise computed during the upload walk, so the
+      // count is meaningful on the abort path too.
+      filesExcludedByScope: scopeExcludedSet.size,
       // Use the snapshot of conflictPaths taken at the moment the abort
       // fired — additional in-flight items may have appended to the
       // shared array after the abort signal, and those should not show
@@ -1403,6 +1525,24 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     });
   }
 
+  // ACL scope-exclusion summary. Emit at most once when one or more candidate
+  // paths fell outside the run's granted `prefixSet` and were skipped from the
+  // upload/delete plan. Informational (NOT an error): the company still syncs
+  // its in-scope subset and the run exits 0. Sample capped at 10 (insertion
+  // order = walk order, deterministic).
+  if (scopeExcludedSet.size > 0) {
+    const samplePaths: string[] = [];
+    for (const p of scopeExcludedSet) {
+      samplePaths.push(p);
+      if (samplePaths.length >= 10) break;
+    }
+    emit({
+      type: "scope-excluded",
+      count: scopeExcludedSet.size,
+      samplePaths,
+    });
+  }
+
   // Codex P1 (5.36.x): if any worker rejected (unhandled error in
   // headRemoteFile / refreshEntityContext / resolveConflict — paths
   // outside the per-item PUT try/catch), we deliberately let the pool
@@ -1429,6 +1569,7 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     filesRefusedStale,
     filesRefusedStalePaths,
     filesExcludedByPolicy: excludedSet.size,
+    filesExcludedByScope: scopeExcludedSet.size,
     conflictPaths,
     aborted: false,
   };

package/src/cli/sync.ts

@@ -241,6 +241,28 @@ export type SyncProgressEvent =
       count: number;
       samplePaths: string[];
       byId: Record<string, number>;
+    }
+  | {
+      /**
+       * Emitted at most ONCE per `share()` call (push leg) when the run is
+       * scoped to a member/guest's ACL prefixes (`prefixSet`) and one or more
+       * candidate paths fell OUTSIDE the granted prefixes. Those paths are
+       * skipped from the upload (and delete) plan instead of being PUT — the
+       * vended child credential is scoped to the granted prefixes, so pushing
+       * them would draw the server's correct 403 `SCOPE_EXCEEDS_PARENT` and
+       * (pre-fix) abort the WHOLE company. This is the push-side analogue of
+       * the pull-side `skip-out-of-scope` action.
+       *
+       * `count` is the number of distinct company-relative paths/prefixes the
+       * scope filter excluded; `samplePaths` carries up to 10 for diagnostic
+       * display. Informational, NOT an error — the company still syncs its
+       * in-scope subset and the run exits 0.
+       *
+       * Not emitted when `count === 0` — silent on a fully in-scope tree.
+       */
+      type: "scope-excluded";
+      count: number;
+      samplePaths: string[];
     };
 
 export interface SyncOptions {
@@ -1877,5 +1899,15 @@ function defaultConsoleLogger(event: SyncProgressEvent): void {
         console.log(`  ... and ${event.files.length - MAX_SHOWN} more`);
       }
     }
+  } else if (event.type === "scope-excluded") {
+    console.log(
+      `  ~ ${event.count} path${event.count === 1 ? "" : "s"} skipped — outside your granted access (synced the in-scope subset):`,
+    );
+    for (const p of event.samplePaths) {
+      console.log(`    · ${p}`);
+    }
+    if (event.count > event.samplePaths.length) {
+      console.log(`    ... and ${event.count - event.samplePaths.length} more`);
+    }
   }
 }