@indigoai-us/hq-cloud 6.14.0 → 6.14.2

package/src/cli/sync-scope.test.ts

@@ -461,4 +461,94 @@ describe("sync — scope-aware download (US-005)", () => {
     expect(second.scopeOrphansRemoved).toBe(0);
     expect(second.scopeOrphansBlocked).toBe(0);
   });
+
+  // ── US-006: sessions prefix push-only pull-scope exclusion ─────────────────
+  // The sessions prefix is PUSH-ONLY: pushed into the vault but never
+  // auto-pulled onto grantee laptops in ANY mode (including `all`, which
+  // otherwise pulls the whole bucket). The engine expresses this as
+  // `excludePrefixes`, applied to the DOWNLOAD filter only — never to
+  // scope-shrink, so an authored/pinned session is never orphaned.
+  describe("sessions push-only exclusion (US-006)", () => {
+    const withSession = () => {
+      REMOTE.current = [
+        { key: "knowledge/readme.md", size: 100, lastModified: new Date(), etag: '"def456"' },
+        { key: "sessions/prs_1/2026-07-11T10-00-00.json", size: 50, lastModified: new Date(), etag: '"sess1"' },
+      ];
+    };
+    const sessionPath = "sessions/prs_1/2026-07-11T10-00-00.json";
+
+    it("AC4: `all` mode subtracts excludePrefixes — a sessions key is skip-out-of-scope; non-session downloads", async () => {
+      withSession();
+      const result = await sync({
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        syncMode: "all",
+        excludePrefixes: ["sessions/"],
+      });
+      // `all` normally pulls everything; the exclusion carves sessions out.
+      expect(result.filesDownloaded).toBe(1);
+      expect(result.filesOutOfScope).toBe(1);
+      expect(fs.existsSync(companyRel("knowledge/readme.md"))).toBe(true);
+      expect(fs.existsSync(companyRel(sessionPath))).toBe(false);
+    });
+
+    it("AC4: excludePrefixes is NOT fed to scope-shrink — a previously-pulled session file is never orphaned", async () => {
+      withSession();
+      // 1. Full pull WITHOUT the exclusion: the session materializes and journals
+      //    as a pulled (direction:"down") entry under an `all`-mode PullRecord.
+      const first = await sync({
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        syncMode: "all",
+      });
+      expect(first.filesDownloaded).toBe(2);
+      expect(fs.existsSync(companyRel(sessionPath))).toBe(true);
+
+      // 2. Full pull WITH the sessions exclusion. The session is now
+      //    skip-out-of-scope (not re-pulled) but MUST NOT be pruned: the exclude
+      //    set never reaches scope-shrink, whose currentPrefixSet stays `[""]`
+      //    (covers everything). If it WERE fed in, the file would be orphaned.
+      const second = await sync({
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        syncMode: "all",
+        excludePrefixes: ["sessions/"],
+      });
+      expect(second.filesOutOfScope).toBe(1);
+      expect(second.scopeOrphansRemoved).toBe(0);
+      expect(second.scopeOrphansBlocked).toBe(0);
+      expect(fs.existsSync(companyRel(sessionPath))).toBe(true);
+    });
+
+    it("AC6: a pinned/in-scope session survives scope-shrink even though excludePrefixes skips its re-pull", async () => {
+      withSession();
+      // Materialize both under all-mode (knowledge sync + an on-demand session get).
+      await sync({ company: "acme", vaultConfig: mockConfig, hqRoot: tmpDir, syncMode: "all" });
+      expect(fs.existsSync(companyRel(sessionPath))).toBe(true);
+
+      // A scoped shared pull whose inclusion prefixSet includes the pinned
+      // session key (as resolvePullScope would after `hq files get` pins it),
+      // plus the push-only sessions exclusion. The session is NOT re-pulled
+      // (exclusion), but the pin keeps it in scope-shrink's currentPrefixSet, so
+      // it is retained rather than orphaned.
+      const scoped = await sync({
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        syncMode: "shared",
+        prefixSet: ["knowledge/", sessionPath],
+        excludePrefixes: ["sessions/"],
+      });
+      expect(scoped.scopeOrphansRemoved).toBe(0);
+      expect(scoped.scopeOrphansBlocked).toBe(0);
+      // Session is not re-downloaded (excluded) but survives on disk...
+      expect(scoped.filesOutOfScope).toBe(1);
+      expect(fs.existsSync(companyRel(sessionPath))).toBe(true);
+      // ...and the in-scope knowledge file is retained too.
+      expect(fs.existsSync(companyRel("knowledge/readme.md"))).toBe(true);
+    });
+  });
 });

package/src/cli/sync.test.ts

@@ -3589,3 +3589,157 @@ describe("reportNewFilesToNotify chunking (server cap = 1000 files/report)", ()
     expect(fetchMock).not.toHaveBeenCalled();
   });
 });
+
+describe("scope-invalid key hardening (companies/ prefix in a company vault — incident 2026-07-11)", () => {
+  let tmpDir: string;
+  let stateDir: string;
+  let journalPath: string;
+
+  beforeEach(() => {
+    clearContextCache();
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-sync-poison-test-"));
+    stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-state-poison-test-"));
+    process.env.HQ_STATE_DIR = stateDir;
+    journalPath = path.join(stateDir, "sync-journal.acme.json");
+    setupFetchMock();
+    // Earlier tests in this file replace the downloadFile implementation with
+    // throwing probes; vi.clearAllMocks() keeps implementations, so restore
+    // the default writer here to keep these tests order-independent.
+    vi.mocked(s3Module.downloadFile).mockReset();
+    vi.mocked(s3Module.downloadFile).mockImplementation(
+      async (_ctx: unknown, _key: string, localPath: string) => {
+        fs.mkdirSync(path.dirname(localPath), { recursive: true });
+        fs.writeFileSync(localPath, "mock file content");
+        return { metadata: {} };
+      },
+    );
+  });
+
+  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("skips a companies/-prefixed remote key instead of erroring the whole company sync", async () => {
+    // The incident shape: 25 poisoned `companies/indigo/…` objects in the
+    // company bucket; the presign download API rejects them
+    // (INVALID_KEY_COMPANIES_SCOPED), so attempting to download errored the
+    // whole company sync and gated heartbeat toolset refreshes fleet-wide.
+    // One bad object must never take down a company sync.
+    vi.mocked(s3Module.listRemoteFiles).mockReset();
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValue([
+      { key: "companies/acme/knowledge/poison.md", size: 10, lastModified: new Date(), etag: '"p1"' },
+      { key: "docs/good.md", size: 5, lastModified: new Date(), etag: '"g1"' },
+    ]);
+    const events: Array<{ type: string; [k: string]: unknown }> = [];
+    const result = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      onEvent: (e) => events.push(e as never),
+    });
+
+    // The good file syncs; the poisoned key is never downloaded.
+    expect(result.aborted).toBe(false);
+    expect(result.filesDownloaded).toBe(1);
+    expect(
+      fs.existsSync(path.join(tmpDir, "companies", "acme", "docs", "good.md")),
+    ).toBe(true);
+    expect(
+      fs.existsSync(
+        path.join(tmpDir, "companies", "acme", "companies", "acme", "knowledge", "poison.md"),
+      ),
+    ).toBe(false);
+    const downloadedKeys = vi
+      .mocked(s3Module.downloadFile)
+      .mock.calls.map((c) => c[1]);
+    expect(downloadedKeys).not.toContain("companies/acme/knowledge/poison.md");
+
+    // Counted as policy-excluded, surfaced as a benign per-key warning event —
+    // deliberately NOT type:"error" (an error event flips the runner to exit 2).
+    expect(result.filesExcludedByPolicy).toBeGreaterThanOrEqual(1);
+    const skipEvents = events.filter((e) => e.type === "skip-invalid-scoped-key");
+    expect(skipEvents).toEqual([
+      { type: "skip-invalid-scoped-key", path: "companies/acme/knowledge/poison.md" },
+    ]);
+    expect(events.filter((e) => e.type === "error")).toEqual([]);
+  });
+
+  it("cleans a doubled-tree journal entry via tombstone (local delete + journal drop) without HEAD-verifying the invalid key", async () => {
+    // A doubled local tree (companies/acme/companies/acme/…) previously
+    // poisoned the bucket; the poisoned objects were deleted server-side.
+    // The journal entry at the invalid key must drain as a tombstone —
+    // local copy removed, journal entry dropped — and must NOT be
+    // HEAD-verified (the presign transport rejects the key, which would
+    // defer the tombstone forever) and must NOT be re-uploaded.
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    const doubled = path.join(companyRoot, "companies", "acme", "knowledge");
+    fs.mkdirSync(doubled, { recursive: true });
+    fs.writeFileSync(path.join(doubled, "poison.md"), "poison content");
+    const crypto = await import("node:crypto");
+    const baseline = crypto
+      .createHash("sha256")
+      .update("poison content")
+      .digest("hex");
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date(Date.now() - 60_000).toISOString(),
+        files: {
+          "companies/acme/knowledge/poison.md": {
+            hash: baseline,
+            size: 14,
+            syncedAt: new Date(Date.now() - 60_000).toISOString(),
+            direction: "up",
+            remoteEtag: "poison-etag",
+          },
+        },
+      }),
+    );
+    // Remote LIST no longer contains the poisoned key (manual cleanup done).
+    vi.mocked(s3Module.listRemoteFiles).mockReset();
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValue([]);
+
+    const result = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+
+    // Cleaned, not re-uploaded: local doubled-tree copy gone, journal dropped.
+    expect(fs.existsSync(path.join(doubled, "poison.md"))).toBe(false);
+    expect(result.filesTombstoned).toBeGreaterThanOrEqual(1);
+    const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+    expect(journal.files["companies/acme/knowledge/poison.md"]).toBeUndefined();
+    // No HEAD verify against the invalid key — the server validator would
+    // reject it (INVALID_KEY_COMPANIES_SCOPED) and defer the cleanup forever.
+    const headKeys = vi
+      .mocked(s3Module.headRemoteFile)
+      .mock.calls.map((c) => c[1]);
+    expect(headKeys).not.toContain("companies/acme/knowledge/poison.md");
+    // Never re-uploaded.
+    expect(vi.mocked(s3Module.uploadFile)).not.toHaveBeenCalled();
+  });
+
+  it("personal-mode pull still downloads companies/{slug}/ keys (local non-cloud companies are legitimate)", async () => {
+    vi.mocked(s3Module.listRemoteFiles).mockReset();
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValue([
+      { key: "companies/localco/notes.md", size: 4, lastModified: new Date(), etag: '"n1"' },
+    ]);
+    const events: Array<{ type: string }> = [];
+    const result = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      personalMode: true,
+      onEvent: (e) => events.push(e as never),
+    });
+    expect(result.filesDownloaded).toBe(1);
+    expect(events.filter((e) => e.type === "skip-invalid-scoped-key")).toEqual([]);
+    expect(fs.existsSync(path.join(tmpDir, "companies", "localco", "notes.md"))).toBe(true);
+  });
+});

package/src/cli/sync.ts

@@ -12,7 +12,11 @@ import type {
   VaultServiceConfig,
   SyncJournal,
 } from "../types.js";
-import type { SyncMode } from "../vault-client.js";
+import { VaultClient, type SyncMode } from "../vault-client.js";
+import {
+  emitCloudTelemetry,
+  type TelemetryClaims,
+} from "../telemetry-events.js";
 import { resolveEntityContext, isExpiringSoon, refreshEntityContext } from "../context.js";
 import { createSyncProgressRecorder } from "../sync-progress.js";
 import {
@@ -333,13 +337,31 @@ export type SyncProgressEvent =
        * pushed it into the runner's `errors[]` and made every watch pass return
        * exit 2; the menubar supervisor then reported that as
        * "auto-sync watcher exited unexpectedly (code=Some(2))" on every tick —
-       * the fleet-wide HQ-SYNC-4 flood. Surfaced here purely for visibility
+       * the HQ-SYNC-4 flood across user machines. Surfaced here purely for visibility
        * (`bytes` is the offending file's size) so a UI/CLI can tell the user
        * which file was too big without treating it as a failure.
        */
       type: "skip-size-limit";
       path: string;
       bytes: number;
+    }
+  | {
+      /**
+       * Emitted by the PULL leg once per remote key skipped because it is
+       * invalid for the vault's scope — today, a `companies/…`-prefixed key in
+       * a company-scoped vault (the server rejects these with
+       * INVALID_KEY_COMPANIES_SCOPED; see hq-pro files-acl validateObjectKey).
+       * Such keys are bucket poisoning from a client with a stale doubled
+       * local tree writing via direct S3 (incident 2026-07-11). Like
+       * `skip-size-limit`, this is deliberately NOT `type: "error"` — one bad
+       * object must never error a whole company sync (erroring gated
+       * heartbeat toolset refreshes fleet-wide in the incident). Surfaced for
+       * visibility + cloud telemetry; per policy
+       * hq-alert-baseline-calibration the healthy baseline is ZERO such keys,
+       * so any occurrence is signal.
+       */
+      type: "skip-invalid-scoped-key";
+      path: string;
     };
 
 export interface SyncOptions {
@@ -409,6 +431,23 @@ export interface SyncOptions {
    * failure can never silently prune the local tree.
    */
   prefixSet?: ScopePrefixInput[];
+  /**
+   * Company-relative prefixes SUBTRACTED from the effective pull scope in EVERY
+   * mode — the push-only set (US-006). Carries `sessions/`: session transcripts
+   * are pushed into the vault but never auto-pulled onto grantee laptops, even
+   * under `syncMode: "all"` (which otherwise pulls the whole bucket). A remote
+   * key downloads iff it is covered by the inclusion scope (`prefixSet`, or all
+   * of `all` mode) AND NOT covered by any `excludePrefixes` entry; excluded
+   * keys are classified `skip-out-of-scope`.
+   *
+   * CRITICAL: this set is applied ONLY to the download filter. It is
+   * deliberately NOT fed into the scope-shrink pass (which keeps using the
+   * inclusion `prefixSet` + pins), so a locally-authored (`direction:"up"`) or
+   * pinned on-demand-materialized session is NEVER orphaned/pruned — it is
+   * merely not re-pulled. The runner derives this from
+   * `resolvePullScope().excludePrefixes`.
+   */
+  excludePrefixes?: ScopePrefixInput[];
   /**
    * When the effective scope shrinks relative to the last pull and the shrink
    * would orphan locally-modified ("dirty") files, `sync()` aborts with a
@@ -444,6 +483,12 @@ export interface SyncOptions {
    * it from disk, so it stays pure/hermetic; undefined degrades safely.
    */
   callerSub?: string;
+  /**
+   * Optional decoded Cognito claims used only for action telemetry attribution
+   * (agentUid when `custom:entityType=agent`). Sync behavior never branches on
+   * this field.
+   */
+  telemetryClaims?: TelemetryClaims | null;
   /**
    * Skip the post-sync `reindex()` refresh (skill wrappers + personal overlay
    * mirrors + workers registry). By default, when a sync changes on-disk
@@ -547,6 +592,14 @@ interface PullRunContext {
   remoteFiles: RemoteFile[];
   syncMode: SyncMode;
   currentPrefixSet: string[];
+  /**
+   * Coalesced push-only exclusion prefixes (US-006: `sessions/`), subtracted
+   * from the download filter in EVERY mode. Kept SEPARATE from
+   * `currentPrefixSet` on purpose: the scope-shrink pass reads only
+   * `currentPrefixSet` (+ pins), so excluded-but-authored/pinned session files
+   * are never orphaned.
+   */
+  currentExcludeSet: string[];
   fileTombstones: ReadonlyMap<string, CompanyTombstone>;
 }
 
@@ -625,6 +678,7 @@ export async function reportNewFilesToNotify(
   companyUid: string,
   companySlug: string,
   files: Array<{ path: string; bytes: number; addedBy: string | null }>,
+  telemetryClaims?: TelemetryClaims | null,
 ): Promise<void> {
   if (files.length === 0) return;
 
@@ -639,16 +693,19 @@ export async function reportNewFilesToNotify(
     return;
   }
   const base = vaultConfig.apiUrl.replace(/\/+$/, "");
+  const telemetryClient = new VaultClient(vaultConfig);
+  const batchCount = Math.ceil(files.length / NOTIFY_FILE_ADDED_MAX_BATCH);
 
   for (let i = 0; i < files.length; i += NOTIFY_FILE_ADDED_MAX_BATCH) {
     const batch = files.slice(i, i + NOTIFY_FILE_ADDED_MAX_BATCH);
+    const batchIndex = Math.floor(i / NOTIFY_FILE_ADDED_MAX_BATCH) + 1;
     const controller = new AbortController();
     const timer = setTimeout(
       () => controller.abort(),
       NOTIFY_FILE_ADDED_TIMEOUT_MS,
     );
     try {
-      await fetch(`${base}/v1/notify/file-added`, {
+      const response = await fetch(`${base}/v1/notify/file-added`, {
         method: "POST",
         headers: {
           Authorization: `Bearer ${token}`,
@@ -665,16 +722,44 @@ export async function reportNewFilesToNotify(
         }),
         signal: controller.signal,
       });
+      void emitCloudTelemetry(telemetryClient, {
+        eventName: "new_files_notification_reported",
+        source: "hq-sync",
+        companyUid,
+        properties: {
+          result: response.ok ? "success" : "failure",
+          fileCount: batch.length,
+          batchIndex,
+          batchCount,
+          statusCode: response.status,
+        },
+      }, { claims: telemetryClaims });
     } catch (err) {
       // Best-effort per chunk: never let notification reporting affect the sync
       // result, and a failed chunk must not abort the remaining chunks.
       logNotifyFailure(err);
+      void emitCloudTelemetry(telemetryClient, {
+        eventName: "new_files_notification_reported",
+        source: "hq-sync",
+        companyUid,
+        properties: {
+          result: "failure",
+          fileCount: batch.length,
+          batchIndex,
+          batchCount,
+          errorCode: safeErrorName(err),
+        },
+      }, { claims: telemetryClaims });
     } finally {
       clearTimeout(timer);
     }
   }
 }
 
+function safeErrorName(err: unknown): string {
+  return err instanceof Error && err.name ? err.name : "error";
+}
+
 /** Log a non-fatal notify failure without ever throwing out of the logger. */
 function logNotifyFailure(err: unknown): void {
   try {
@@ -724,6 +809,7 @@ async function syncWithOperationLockHeld(
   const plan = planPull(run);
 
   emitPullPlan(run.emit, plan);
+  reportInvalidScopedKeys(run, plan);
 
   const scopePlan = planScopeShrink(run);
   const scopeRun = executeScopeShrink(run, scopePlan);
@@ -795,6 +881,13 @@ async function buildPullContext(options: SyncOptions): Promise<PullRunContext> {
   const syncMode: SyncMode = options.syncMode ?? "all";
   const currentPrefixSet: string[] =
     syncMode === "all" ? [""] : coalescePrefixes(options.prefixSet ?? []);
+  // Push-only exclusions (US-006). Coalesced independently of `currentPrefixSet`
+  // and applied to EVERY mode's download filter — including `all` — but kept out
+  // of the scope-shrink inputs (see `planScopeShrink`). Empty when the caller
+  // passes nothing (legacy behavior: no exclusions).
+  const currentExcludeSet: string[] = coalescePrefixes(
+    options.excludePrefixes ?? [],
+  );
 
   const remoteFiles = await listRemoteFiles(ctx);
   const fileTombstones =
@@ -817,6 +910,7 @@ async function buildPullContext(options: SyncOptions): Promise<PullRunContext> {
     remoteFiles,
     syncMode,
     currentPrefixSet,
+    currentExcludeSet,
     fileTombstones,
   };
 }
@@ -831,6 +925,7 @@ function planPull(run: PullRunContext): PullPlan {
     run.options.teamSyncedSlugs ?? null,
     run.currentPrefixSet,
     run.fileTombstones,
+    run.currentExcludeSet,
   );
 }
 
@@ -847,6 +942,33 @@ function emitPullPlan(emit: SyncEventEmitter, plan: PullPlan): void {
   });
 }
 
+/**
+ * Surface scope-invalid remote keys the planner skipped (see the
+ * `invalidScopedKeys` doc on PullPlan). One warning event per key on the
+ * existing sync event channel (deliberately NOT `type: "error"` — see the
+ * `skip-invalid-scoped-key` event doc), plus one best-effort cloud telemetry
+ * event on the channel sync already uses (emitCloudTelemetry). Per policy
+ * hq-alert-baseline-calibration the documented healthy baseline is ZERO
+ * INVALID_KEY_COMPANIES_SCOPED occurrences fleet-wide, so consumers can alert
+ * on any non-zero count with no threshold tuning.
+ */
+function reportInvalidScopedKeys(run: PullRunContext, plan: PullPlan): void {
+  if (plan.invalidScopedKeys.length === 0) return;
+  for (const key of plan.invalidScopedKeys) {
+    run.emit({ type: "skip-invalid-scoped-key", path: key });
+  }
+  void emitCloudTelemetry(new VaultClient(run.vaultConfig), {
+    eventName: "sync_invalid_scoped_key_skipped",
+    source: "hq-sync",
+    companyUid: run.ctx.uid,
+    properties: {
+      count: plan.invalidScopedKeys.length,
+      errorCode: "INVALID_KEY_COMPANIES_SCOPED",
+      leg: "pull",
+    },
+  }, { claims: run.options.telemetryClaims });
+}
+
 function createPullCounters(): PullCounters {
   return {
     filesDownloaded: 0,
@@ -870,6 +992,12 @@ function planScopeShrink(run: PullRunContext): ScopeShrinkPlanState {
     journal: run.journal,
     hqRoot: run.companyRoot,
     lastPrefixSet,
+    // INCLUSION scope only (+ pins, already folded into currentPrefixSet by the
+    // resolver). The push-only exclude set (US-006: `sessions/`) is DELIBERATELY
+    // NOT subtracted here: a session file that was authored locally
+    // (`direction:"up"`) or pinned + materialized on demand must never be
+    // orphaned just because sessions are excluded from the download filter.
+    // Feeding `currentExcludeSet` in here would prune exactly those files.
     currentPrefixSet: run.currentPrefixSet,
     callerSub: run.options.callerSub,
     protectUnknownAuthors: true,
@@ -1429,6 +1557,7 @@ async function emitAndReportNewFiles(
     run.ctx.uid,
     run.ctx.slug,
     enrichedNewFiles,
+    run.options.telemetryClaims,
   );
 }
 
@@ -1438,6 +1567,29 @@ async function verifyPlannedJournalTombstones(
 ): Promise<void> {
   if (plan.tombstones.length === 0) return;
 
+  // Scope-invalid journal keys (company mode, `companies/…` prefix) skip the
+  // HEAD verify: the presign transport's server validator rejects such keys
+  // outright (INVALID_KEY_COMPANIES_SCOPED), so a HEAD can never succeed and
+  // would defer the tombstone forever — leaving the poisoned journal entry
+  // (and its doubled-tree local file) re-firing on every sync. The key can
+  // never legitimately exist in a company vault, so treating it as verified
+  // is safe: the executor cleans the local copy + journal entry instead of
+  // the push leg ever re-uploading it (tombstone-not-reupload).
+  const autoVerified: string[] = [];
+  const toHeadVerify: string[] = [];
+  for (const key of plan.tombstones) {
+    if (run.options.personalMode !== true && key.startsWith("companies/")) {
+      autoVerified.push(key);
+    } else {
+      toHeadVerify.push(key);
+    }
+  }
+  plan.tombstones = toHeadVerify;
+  if (plan.tombstones.length === 0) {
+    plan.tombstones = autoVerified;
+    return;
+  }
+
   await primeObjectTransport(run.ctx, "get", plan.tombstones);
 
   const HEAD_VERIFY_CONCURRENCY = 5;
@@ -1466,7 +1618,7 @@ async function verifyPlannedJournalTombstones(
       if (k !== null) verified.push(k);
     }
   }
-  plan.tombstones = verified;
+  plan.tombstones = [...autoVerified, ...verified];
 }
 
 function executeJournalTombstoneDeletes(
@@ -1545,7 +1697,19 @@ function finalizePullRun(
     scopeRun.scopeOrphansRemoved > 0;
   if (!run.options.skipReindex && changedOnDisk) {
     try {
-      reindex({ repoRoot: run.hqRoot, skipLock: true });
+      const result = reindex({ repoRoot: run.hqRoot, skipLock: true });
+      void emitCloudTelemetry(new VaultClient(run.vaultConfig), {
+        eventName: "reindex_run",
+        source: "hq-sync",
+        companyUid: run.ctx.uid,
+        properties: {
+          result: result.status === 0 ? "completed" : "failed",
+          statusCode: result.status,
+          lockResult: "skipped",
+          changedCount:
+            counters.changedPaths.length + scopeRun.changedPaths.length,
+        },
+      }, { claims: run.options.telemetryClaims });
     } catch (err) {
       logPostSyncMaintenanceFailure("post-sync reindex", run.hqRoot, err);
       // best-effort: a post-sync refresh failure never fails the sync
@@ -1780,6 +1944,15 @@ interface PullPlan {
    * `filesToDelete` axis; the per-item executor applies the local delete.
    */
   filesToTombstoneDelete: number;
+  /**
+   * Remote keys skipped because they are invalid for the vault's scope
+   * (company mode only: literal `companies/…` keys — bucket poisoning from a
+   * doubled-tree client via direct S3). Counted in `filesExcludedByPolicy`;
+   * carried by key so the caller can log one warning per key and emit
+   * telemetry. Healthy baseline is an empty array (policy
+   * hq-alert-baseline-calibration: zero expected, any occurrence is signal).
+   */
+  invalidScopedKeys: string[];
 }
 
 /**
@@ -1847,8 +2020,18 @@ function computePullPlan(
   // preserves the legacy behavior bit-for-bit. (Named `fileTombstones` to avoid
   // shadowing the local `tombstones` string[] — the journal-vs-LIST delete set.)
   fileTombstones: ReadonlyMap<string, CompanyTombstone> = new Map(),
+  // Push-only exclusion prefixes (US-006: `sessions/`). Keys covered by any of
+  // these are classified `skip-out-of-scope` in EVERY mode — including `all` —
+  // AFTER passing the inclusion check. Empty (the default) preserves legacy
+  // behavior bit-for-bit. Applied ONLY here (the download filter), never to
+  // scope-shrink, so an authored/pinned excluded key is not re-pulled yet also
+  // never orphaned.
+  excludePrefixes: readonly ScopePrefixInput[] = [],
 ): PullPlan {
   const items: PullPlanItem[] = [];
+  // Company-mode remote keys invalid for the vault's scope (`companies/…` in a
+  // company bucket) — collected so the caller can warn + emit telemetry.
+  const invalidScopedKeys: string[] = [];
   // Clean/current/non-divergent files missing locally — collected here, then
   // resolved post-loop by the bulk-asymmetry decision (tombstone vs. restore).
   const intentionalDeleteCandidates: Array<{
@@ -1874,6 +2057,23 @@ function computePullPlan(
       continue;
     }
 
+    // Scope-invalid key filter (incident 2026-07-11). A company vault bucket
+    // is already company-scoped, so a literal `companies/…` key can only be
+    // bucket poisoning — a client with a stale doubled local tree
+    // (companies/{slug}/companies/{slug}/…) pushing via the direct-S3 STS
+    // transport, which bypasses the server validator. The presign download
+    // API rejects these keys (INVALID_KEY_COMPANIES_SCOPED), so attempting to
+    // download them errors the WHOLE company sync. Skip them here — one bad
+    // object must never take down a company sync — and record them on the
+    // plan so the caller can warn + emit telemetry (baseline is zero; any
+    // occurrence is signal). Mirrors the personalMode/malformed-key filters
+    // above. Upload-side counterpart: validateVaultUploadKey in s3.ts.
+    if (!personalMode && remoteFile.key.startsWith("companies/")) {
+      invalidScopedKeys.push(remoteFile.key);
+      items.push({ action: "skip-excluded-policy", remoteFile, localPath });
+      continue;
+    }
+
     if (
       personalMode &&
       remoteFile.key.startsWith("companies/") &&
@@ -1917,6 +2117,20 @@ function computePullPlan(
       continue;
     }
 
+    // Push-only exclusion filter (US-006). A key that PASSED the inclusion check
+    // above is STILL not downloaded if it falls under a push-only exclude prefix
+    // (`sessions/`). This is what makes sessions push-only in EVERY mode — it
+    // subtracts from `all` (whose `prefixSet` is `[""]`, covering everything)
+    // and from an owner's role-wide scope alike. Empty `excludePrefixes` (the
+    // default) makes this a no-op. Deliberately AFTER inclusion and reported on
+    // the same `filesOutOfScope` axis. The matching local file (if a session was
+    // previously pulled, authored locally, or pinned+materialized) is NOT pruned
+    // here or by scope-shrink — see `planScopeShrink`, which never sees this set.
+    if (isCoveredByAny(remoteFile.key, excludePrefixes)) {
+      items.push({ action: "skip-out-of-scope", remoteFile, localPath });
+      continue;
+    }
+
     // LIST gives us no kind signal for the remote object — we don't
     // know whether this key is a regular file or a symlink record
     // until we either HEAD it (expensive — N extra calls per pull) or
@@ -2420,6 +2634,7 @@ function computePullPlan(
     filesOutOfScope,
     filesToTombstoneDelete,
     tombstones,
+    invalidScopedKeys,
   };
 }
 
@@ -2502,5 +2717,9 @@ function defaultConsoleLogger(event: SyncProgressEvent): void {
     console.warn(
       `  ! ${event.path} skipped — ${mb} MB exceeds the 50 MB sync size limit`,
     );
+  } else if (event.type === "skip-invalid-scoped-key") {
+    console.warn(
+      `  ! ${event.path} skipped — invalid 'companies/'-prefixed key in a company-scoped vault (bucket poisoning; INVALID_KEY_COMPANIES_SCOPED)`,
+    );
   }
 }