@indigoai-us/hq-cloud 6.14.0 → 6.14.2

package/src/cli/accept.ts

@@ -14,6 +14,7 @@ import {
   VaultPermissionDeniedError,
 } from "../vault-client.js";
 import type { Membership } from "../vault-client.js";
+import { emitCloudTelemetry } from "../telemetry-events.js";
 
 export interface AcceptOptions {
   /** Raw token or magic link (hq://accept/<token>) */
@@ -78,8 +79,26 @@ export async function accept(options: AcceptOptions): Promise<AcceptResult> {
       }
     }
 
+    void emitCloudTelemetry(client, {
+      eventName: "membership_accept",
+      source: "hq-cli",
+      companyUid: membership.companyUid,
+      properties: {
+        role: membership.role,
+        result: "success",
+      },
+    });
+
     return { membership, companySlug };
   } catch (err) {
+    void emitCloudTelemetry(client, {
+      eventName: "membership_accept",
+      source: "hq-cli",
+      properties: {
+        result: "failure",
+        errorCode: classifyAcceptError(err),
+      },
+    });
     if (err instanceof VaultAuthError) {
       throw new Error("Authentication failed — run `hq auth` to refresh your session");
     }
@@ -95,3 +114,11 @@ export async function accept(options: AcceptOptions): Promise<AcceptResult> {
     throw err;
   }
 }
+
+function classifyAcceptError(err: unknown): string {
+  if (err instanceof VaultAuthError) return "auth";
+  if (err instanceof VaultConflictError) return "conflict";
+  if (err instanceof VaultNotFoundError) return "not_found";
+  if (err instanceof VaultPermissionDeniedError) return "permission";
+  return "error";
+}

package/src/cli/invite.ts

@@ -14,6 +14,7 @@ import {
   VaultConflictError,
 } from "../vault-client.js";
 import type { MembershipRole, Membership } from "../vault-client.js";
+import { emitCloudTelemetry } from "../telemetry-events.js";
 
 export interface InviteOptions {
   /** Target — email address or person slug/uid */
@@ -83,6 +84,17 @@ export async function invite(options: InviteOptions): Promise<InviteResult> {
     });
 
     const magicLink = `hq://accept/${result.inviteToken}`;
+    void emitCloudTelemetry(client, {
+      eventName: "membership_invite",
+      source: "hq-cli",
+      companyUid,
+      properties: {
+        role,
+        result: "success",
+        targetType: isEmail ? "email" : "person",
+        allowedPrefixCount: allowedPrefixes?.length ?? 0,
+      },
+    });
 
     return {
       inviteToken: result.inviteToken,
@@ -90,6 +102,18 @@ export async function invite(options: InviteOptions): Promise<InviteResult> {
       membership: result.membership,
     };
   } catch (err) {
+    void emitCloudTelemetry(client, {
+      eventName: "membership_invite",
+      source: "hq-cli",
+      companyUid,
+      properties: {
+        role,
+        result: "failure",
+        errorCode: classifyInviteError(err),
+        targetType: isEmail ? "email" : "person",
+        allowedPrefixCount: allowedPrefixes?.length ?? 0,
+      },
+    });
     if (err instanceof VaultAuthError) {
       throw new Error("Authentication failed — run `hq auth` to refresh your session");
     }
@@ -103,6 +127,13 @@ export async function invite(options: InviteOptions): Promise<InviteResult> {
   }
 }
 
+function classifyInviteError(err: unknown): string {
+  if (err instanceof VaultAuthError) return "auth";
+  if (err instanceof VaultPermissionDeniedError) return "permission";
+  if (err instanceof VaultConflictError) return "conflict";
+  return "error";
+}
+
 /**
  * List pending invites for a company.
  */

package/src/cli/promote.ts

@@ -13,6 +13,7 @@ import {
   VaultConflictError,
 } from "../vault-client.js";
 import type { MembershipRole, Membership } from "../vault-client.js";
+import { emitCloudTelemetry } from "../telemetry-events.js";
 
 export interface PromoteOptions {
   /** Person slug or UID of the member to promote */
@@ -66,8 +67,30 @@ export async function promote(options: PromoteOptions): Promise<PromoteResult> {
       companyUid,
     });
 
+    void emitCloudTelemetry(client, {
+      eventName: "membership_promote",
+      source: "hq-cli",
+      companyUid,
+      properties: {
+        role: newRole,
+        result: "success",
+        allowedPrefixCount: allowedPrefixes?.length ?? 0,
+      },
+    });
+
     return { membership };
   } catch (err) {
+    void emitCloudTelemetry(client, {
+      eventName: "membership_promote",
+      source: "hq-cli",
+      companyUid,
+      properties: {
+        role: newRole,
+        result: "failure",
+        errorCode: classifyPromoteError(err),
+        allowedPrefixCount: allowedPrefixes?.length ?? 0,
+      },
+    });
     if (err instanceof VaultAuthError) {
       throw new Error("Authentication failed — run `hq auth` to refresh your session");
     }
@@ -84,6 +107,14 @@ export async function promote(options: PromoteOptions): Promise<PromoteResult> {
   }
 }
 
+function classifyPromoteError(err: unknown): string {
+  if (err instanceof VaultAuthError) return "auth";
+  if (err instanceof VaultPermissionDeniedError) return "permission";
+  if (err instanceof VaultNotFoundError) return "not_found";
+  if (err instanceof VaultConflictError) return "conflict";
+  return "error";
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------

package/src/cli/reindex.test.ts

@@ -389,17 +389,46 @@ describe("reindex", () => {
     expect(fs.readFileSync(path.join(link, "note.md"), "utf-8")).toBe("owned by personal\n");
   });
 
-  // ── operation lock (mutual exclusion with sync/rescue) ──────────────────
+  // ── operation lock: reindex uses a SEPARATE scope from sync/rescue ──────
+
+  // Regression for feedback_ed98d810 (the "hq reindex indefinite hang"): when
+  // a watch-mode hq-sync-runner holds the per-root "operation" lock for its
+  // whole lifetime, a shared lock starved `hq reindex` forever. reindex now
+  // takes its own "reindex" scope, so it must run to completion even while the
+  // sync/watch "operation" lock is held by a LIVE holder.
+  it("completes while the sync/watch operation lock is held (no starvation)", () => {
+    // Simulate the long-lived watch runner holding the "operation"-scope lock.
+    // pid = this process → the lock probes it as ALIVE (a live same-PID holder
+    // is treated as busy, never reclaimed), so it is a genuine live holder.
+    const syncLock = lockPathFor(root); // default "operation" scope
+    fs.mkdirSync(path.dirname(syncLock), { recursive: true });
+    fs.writeFileSync(
+      syncLock,
+      JSON.stringify({
+        pid: process.pid,
+        command: "sync",
+        startedAt: new Date(0).toISOString(),
+        hqRoot: root,
+      }),
+    );
+    // Even with a zero-wait bound (never block), reindex acquires its OWN scope
+    // and finishes — proving the operation lock no longer gates it.
+    const { status } = reindex({ repoRoot: root, lockTimeoutSec: 0 });
+    expect(status).toBe(0);
+    expect(fs.existsSync(path.join(root, ".claude/skills"))).toBe(true);
+    // The sync/watch holder is untouched.
+    expect(fs.existsSync(syncLock)).toBe(true);
+  });
 
-  it("refuses (OPERATION_LOCKED_EXIT) when another op holds this root's lock (lockTimeoutSec:0)", () => {
-    // A live holder in another process (pid 1) → with lockTimeoutSec:0 reindex
-    // refuses immediately and does no work. (The new default is to WAIT; the
-    // wait-then-acquire path is covered in operation-lock.test.ts.)
-    const lp = lockPathFor(root);
+  it("refuses (OPERATION_LOCKED_EXIT) when another reindex holds the reindex-scope lock (lockTimeoutSec:0)", () => {
+    // reindex-vs-reindex is still mutually exclusive. A live holder on the
+    // "reindex" scope → with lockTimeoutSec:0 reindex refuses immediately and
+    // does no work. (The wait-then-acquire path is in operation-lock.test.ts.)
+    const lp = lockPathFor(root, "reindex");
     fs.mkdirSync(path.dirname(lp), { recursive: true });
     fs.writeFileSync(
       lp,
-      JSON.stringify({ pid: 1, command: "sync", startedAt: new Date(0).toISOString(), hqRoot: root }),
+      JSON.stringify({ pid: 1, command: "reindex", startedAt: new Date(0).toISOString(), hqRoot: root }),
     );
     const before = fs.existsSync(path.join(root, ".claude/skills"));
     const { status } = reindex({ repoRoot: root, lockTimeoutSec: 0 });
@@ -408,22 +437,24 @@ describe("reindex", () => {
     expect(fs.existsSync(path.join(root, ".claude/skills"))).toBe(before);
   });
 
-  it("skipLock bypasses the lock (internal sync/rescue caller path)", () => {
-    const lp = lockPathFor(root);
+  it("skipLock bypasses the reindex lock (internal sync/rescue caller path)", () => {
+    const lp = lockPathFor(root, "reindex");
     fs.mkdirSync(path.dirname(lp), { recursive: true });
     fs.writeFileSync(
       lp,
-      JSON.stringify({ pid: 1, command: "sync", startedAt: new Date(0).toISOString(), hqRoot: root }),
+      JSON.stringify({ pid: 1, command: "reindex", startedAt: new Date(0).toISOString(), hqRoot: root }),
     );
-    // Even with a live holder on record, the internal caller (which already
-    // holds the lock) runs to completion.
+    // Even with a live reindex holder on record, the internal caller (which
+    // serializes reindex itself at the tail of a pass) runs to completion.
     const { status } = reindex({ repoRoot: root, skipLock: true });
     expect(status).toBe(0);
     expect(fs.existsSync(path.join(root, ".claude/skills"))).toBe(true);
   });
 
-  it("releases the lock after a normal run (no leftover lock file)", () => {
+  it("releases the reindex-scope lock after a normal run (no leftover lock file)", () => {
     reindex({ repoRoot: root });
+    expect(fs.existsSync(lockPathFor(root, "reindex"))).toBe(false);
+    // ...and never created the sync/rescue "operation" lock.
     expect(fs.existsSync(lockPathFor(root))).toBe(false);
   });
 

package/src/cli/reindex.ts

@@ -25,29 +25,45 @@ import {
   OPERATION_LOCK_UNWRITABLE_EXIT,
   type LockHandle,
 } from "../operation-lock.js";
+import {
+  emitCloudTelemetry,
+  type CloudTelemetryClient,
+  type TelemetryClaims,
+} from "../telemetry-events.js";
 
 export interface ReindexOptions {
   /** HQ root to operate on. Defaults to process.cwd(). */
   repoRoot?: string;
   /**
-   * Skip the per-root operation lock. Internal callers (`sync()` / `rescue()`)
-   * already hold the lock for this root and pass `true` so reindex doesn't try
-   * to re-acquire it and refuse against their own live PID. Standalone callers
-   * (`hq reindex`, the reindex hook) leave it falsy so reindex is mutually
-   * exclusive with a running sync/rescue.
+   * Skip reindex's own per-root "reindex"-scope lock. Internal callers
+   * (`sync()` / `rescue()`) run reindex inline at the tail of a pass they
+   * already serialize, and pass `true` so a standalone `hq reindex` holding the
+   * reindex lock never blocks the sync/rescue tail (reindex is idempotent and
+   * re-run every pass, so a benign overlap self-heals). Standalone callers
+   * (`hq reindex`, the reindex hook) leave it falsy so concurrent reindexes are
+   * mutually exclusive.
    */
   skipLock?: boolean;
   /**
-   * Bounded wait (seconds) for the per-root operation lock when a sync/rescue
-   * is already running. `0` → refuse immediately; omitted → inherit
+   * Bounded wait (seconds) for the per-root "reindex"-scope lock when another
+   * reindex is already running. `0` → refuse immediately; omitted → inherit
    * `HQ_OP_LOCK_TIMEOUT` / infinite wait. Ignored when `skipLock` is set.
    *
-   * NB: standalone `hq reindex` waits by default, which is what a human running
-   * it wants. The hq-core reindex HOOK (Stop / PostToolUse) should set a small
-   * `HQ_OP_LOCK_TIMEOUT` (or `0`) so a hook fired mid-sync never blocks the
-   * interactive agent indefinitely.
+   * NB: reindex uses a lock scope SEPARATE from sync/rescue's "operation" lock,
+   * so a long-lived watch-mode sync-runner (which holds the operation lock for
+   * its whole lifetime) can never starve a standalone `hq reindex`
+   * (feedback_ed98d810). Standalone `hq reindex` waits by default, which is what
+   * a human running it wants; the hq-core reindex HOOK (Stop / PostToolUse)
+   * should set a small `HQ_OP_LOCK_TIMEOUT` (or `0`) so a hook fired while
+   * another reindex runs never blocks the interactive agent indefinitely.
    */
   lockTimeoutSec?: number;
+  /** Optional hq-pro ACTION telemetry sink. Omitted in tests/standalone hooks. */
+  telemetryClient?: CloudTelemetryClient | null;
+  telemetryClaims?: TelemetryClaims | null;
+  telemetrySessionId?: string;
+  telemetryCompanyUid?: string;
+  changedCount?: number;
 }
 
 export interface ReindexResult {
@@ -202,23 +218,32 @@ export function reindex(opts: ReindexOptions = {}): ReindexResult {
   const rawRoot = opts.repoRoot ?? process.cwd();
   if (!isDir(rawRoot)) {
     warn(`reindex: REPO_ROOT '${rawRoot}' is not a directory`);
-    return { status: 1 };
+    const result = { status: 1 };
+    emitReindexTelemetry(opts, result, "not_attempted");
+    return result;
   }
   const root = path.resolve(rawRoot);
 
-  // Acquire the per-root operation lock unless an internal caller (sync/rescue,
-  // which already hold it) opted out. A live holder → refuse fast with the
-  // holder's command + PID. The whole body runs inside the try so the lock is
-  // released on every exit path (the process-level signal/exit hooks are the
-  // crash backstop).
+  // Acquire the per-root "reindex"-scope lock unless an internal caller
+  // (sync/rescue) opted out. This scope is SEPARATE from sync/rescue's
+  // "operation" lock, so a long-lived watch-mode sync-runner holding the
+  // operation lock never starves us (feedback_ed98d810) — we only contend with
+  // other reindexes. A live holder → refuse fast with the holder's command +
+  // PID. The whole body runs inside the try so the lock is released on every
+  // exit path (the process-level signal/exit hooks are the crash backstop).
   let opLock: LockHandle | null = null;
   if (!opts.skipLock) {
     try {
-      opLock = acquireOperationLock(root, "reindex", { timeoutSec: opts.lockTimeoutSec });
+      opLock = acquireOperationLock(root, "reindex", {
+        scope: "reindex",
+        timeoutSec: opts.lockTimeoutSec,
+      });
     } catch (err) {
       if (err instanceof OperationLockedError) {
         warn(err.message);
-        return { status: OPERATION_LOCKED_EXIT };
+        const result = { status: OPERATION_LOCKED_EXIT };
+        emitReindexTelemetry(opts, result, "locked");
+        return result;
       }
       if (err instanceof OperationLockUnwritableError) {
         // The lock dir isn't writable (e.g. macOS EPERM / Linux EACCES on a
@@ -227,7 +252,9 @@ export function reindex(opts: ReindexOptions = {}): ReindexResult {
         // and exit cleanly instead of crashing with a raw `EPERM ... open`
         // (HQ-CLI-2).
         warn(err.message);
-        return { status: OPERATION_LOCK_UNWRITABLE_EXIT };
+        const result = { status: OPERATION_LOCK_UNWRITABLE_EXIT };
+        emitReindexTelemetry(opts, result, "unwritable");
+        return result;
       }
       throw err;
     }
@@ -548,8 +575,34 @@ export function reindex(opts: ReindexOptions = {}): ReindexResult {
     );
   }
 
-  return { status: 0 };
+  const result = { status: 0 };
+  emitReindexTelemetry(opts, result, opts.skipLock ? "skipped" : "acquired");
+  return result;
   } finally {
     opLock?.release();
   }
 }
+
+function emitReindexTelemetry(
+  opts: ReindexOptions,
+  result: ReindexResult,
+  lockResult: string,
+): void {
+  void emitCloudTelemetry(
+    opts.telemetryClient,
+    {
+      eventName: "reindex_run",
+      source: "hq-reindex",
+      ...(opts.telemetryCompanyUid ? { companyUid: opts.telemetryCompanyUid } : {}),
+      ...(opts.telemetrySessionId ? { sessionId: opts.telemetrySessionId } : {}),
+      properties: {
+        result: result.status === 0 ? "completed" : "failed",
+        statusCode: result.status,
+        lockResult,
+        changedCount: opts.changedCount ?? 0,
+        skipLockState: opts.skipLock === true ? "skipped" : "acquired",
+      },
+    },
+    { claims: opts.telemetryClaims },
+  );
+}

package/src/cli/share.test.ts

@@ -1265,8 +1265,8 @@ describe("share", () => {
   });
 
   it("a file over the size limit is a benign skip-size-limit event, NEVER an error (HQ-SYNC-4 exit-2 flood)", async () => {
-    // Regression for the fleet-wide "auto-sync watcher exited unexpectedly
-    // (code=Some(2))" flood (HQ-SYNC-4, ~93k events across 60+ machines). An
+    // Regression for the "auto-sync watcher exited unexpectedly
+    // (code=Some(2))" flood (HQ-SYNC-4, ~93k events across 60+ user machines). An
     // oversized file is a permanent, benign skip — it exceeds the 50 MB cap on
     // EVERY pass, forever. Emitting it as `type: "error"` pushed it into the
     // runner's `errors[]`, so the pass returned exit 2, which the menubar
@@ -4992,3 +4992,140 @@ describe("currency-gated: journal version 2 fixtures", () => {
     });
   });
 });
+
+describe("scope-invalid key hardening on push (doubled companies/ tree — incident 2026-07-11)", () => {
+  let tmpDir: string;
+  let stateDir: string;
+
+  beforeEach(() => {
+    clearContextCache();
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-share-poison-test-"));
+    stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-state-poison-test-"));
+    process.env.HQ_STATE_DIR = stateDir;
+    setupFetchMock();
+    // Earlier describes in this file don't all clear call history; reset it
+    // here so uploaded-key assertions below are order-independent.
+    vi.mocked(uploadFile).mockClear();
+    vi.mocked(uploadSymlink).mockClear();
+    vi.mocked(headRemoteFile).mockClear();
+    vi.mocked(deleteRemoteFile).mockClear();
+    vi.mocked(uploadFile).mockResolvedValue({ etag: '"upload-etag"' });
+    vi.mocked(uploadSymlink).mockResolvedValue({ etag: '"upload-symlink-etag"' });
+    vi.mocked(headRemoteFile).mockResolvedValue(null);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.clearAllMocks();
+    vi.mocked(uploadFile).mockResolvedValue({ etag: '"upload-etag"' });
+    vi.mocked(uploadSymlink).mockResolvedValue({ etag: '"upload-symlink-etag"' });
+    vi.mocked(headRemoteFile).mockResolvedValue(null);
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    fs.rmSync(stateDir, { recursive: true, force: true });
+    delete process.env.HQ_STATE_DIR;
+  });
+
+  it("refuses to upload doubled-tree companies/ keys in company mode — clear per-key warning, never an error", async () => {
+    // The incident writer: a stale doubled local tree
+    // companies/acme/companies/acme/… would push literal `companies/…` keys
+    // via the direct-S3 STS transport, poisoning the bucket with keys the
+    // presign download API rejects (INVALID_KEY_COMPANIES_SCOPED) for every
+    // other machine. The push planner must refuse them up front.
+    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");
+    fs.mkdirSync(path.join(companyRoot, "docs"), { recursive: true });
+    fs.writeFileSync(path.join(companyRoot, "docs", "good.md"), "good");
+
+    const events: Array<{ type?: string; path?: string }> = [];
+    const result = await share({
+      paths: [companyRoot],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      onEvent: (e) => events.push(e as { type?: string }),
+    });
+
+    expect(result.aborted).toBe(false);
+    expect(result.filesUploaded).toBe(1);
+    const uploadedKeys = vi.mocked(uploadFile).mock.calls.map((c) => c[2]);
+    expect(uploadedKeys).toEqual(["docs/good.md"]);
+
+    // Per-key warning on the existing event channel, never type:"error"
+    // (an error event flips the runner pass to exit 2 — the flood class).
+    const skipEvents = events.filter((e) => e.type === "skip-invalid-scoped-key");
+    expect(skipEvents.map((e) => e.path)).toEqual([
+      "companies/acme/knowledge/poison.md",
+    ]);
+    expect(events.some((e) => e.type === "error")).toBe(false);
+  });
+
+  it("tombstones (journal drop, no remote HEAD/DELETE) a companies/ journal key in company mode instead of re-uploading", async () => {
+    // Delete-propagation on a poisoned journal entry: HEAD/DeleteObject on a
+    // companies/-prefixed key would be rejected by the presign transport's
+    // server validator, so the delete plan must route it straight to
+    // toTombstone — journal entry drained, no remote call, no re-upload.
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const journalPath = path.join(stateDir, "sync-journal.acme.json");
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "companies/acme/knowledge/poison.md": {
+            hash: "poison-hash",
+            size: 6,
+            syncedAt: new Date().toISOString(),
+            direction: "up",
+            remoteEtag: "poison-etag",
+          },
+        },
+      }),
+    );
+
+    const result = await share({
+      paths: [companyRoot],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      skipUnchanged: true,
+      propagateDeletes: true,
+      propagateDeletePolicy: "currency-gated",
+    });
+
+    expect(result.aborted).toBe(false);
+    // Tombstoned: journal entry dropped without any remote HEAD or DELETE.
+    expect(result.filesTombstoned).toBe(1);
+    expect(result.filesDeleted).toBe(0);
+    expect(headRemoteFile).not.toHaveBeenCalled();
+    expect(deleteRemoteFile).not.toHaveBeenCalled();
+    expect(uploadFile).not.toHaveBeenCalled();
+    const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+    expect(journal.files["companies/acme/knowledge/poison.md"]).toBeUndefined();
+  });
+
+  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 });
+    fs.writeFileSync(path.join(localCo, "notes.md"), "n");
+
+    const events: Array<{ type?: string }> = [];
+    const result = await share({
+      paths: [localCo],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      personalMode: true,
+      journalSlug: "personal-vault",
+      onEvent: (e) => events.push(e as { type?: string }),
+    });
+
+    expect(result.aborted).toBe(false);
+    const uploadedKeys = vi.mocked(uploadFile).mock.calls.map((c) => c[2]);
+    expect(uploadedKeys).toContain("companies/localco/notes.md");
+    expect(events.filter((e) => e.type === "skip-invalid-scoped-key")).toEqual([]);
+  });
+});

package/src/cli/share.ts

@@ -1047,12 +1047,34 @@ function createShareCounters(): ShareCounters {
 }
 
 async function buildSharePlans(run: PushRunContext): Promise<SharePlans> {
-  const filesToShare = collectFiles(
+  const collected = collectFiles(
     run.paths,
     run.hqRoot,
     run.syncRoot,
     run.shouldSync,
   );
+  // Scope-invalid key filter (incident 2026-07-11). In company mode the sync
+  // root IS the company folder, so a local entry whose vault key starts with
+  // `companies/` can only come from a stale doubled local tree
+  // (companies/{slug}/companies/{slug}/…). Uploading it poisons the bucket
+  // with keys the server validator rejects (INVALID_KEY_COMPANIES_SCOPED) —
+  // the direct-S3 STS transport bypasses server validation. Refuse them here
+  // with a per-key warning; uploadFile/uploadSymlink's validateVaultUploadKey
+  // is the belt-and-suspenders backstop. The pull leg's journal-tombstone
+  // path then CLEANS the doubled tree (local delete + journal drop) instead
+  // of this leg ever re-uploading it. Personal vaults legitimately carry
+  // `companies/{slug}/…` keys, so this only applies in company mode.
+  const filesToShare =
+    run.options.personalMode === true
+      ? collected
+      : collected.filter((entry) => {
+          if (!entry.relativePath.startsWith("companies/")) return true;
+          run.emit({
+            type: "skip-invalid-scoped-key",
+            path: entry.relativePath,
+          });
+          return false;
+        });
   const pushPlan = computePushPlan(
     filesToShare,
     run.journal,
@@ -1069,6 +1091,7 @@ async function buildSharePlans(run: PushRunContext): Promise<SharePlans> {
         run.shouldSync,
         run.propagateDeletePolicy,
         run.ctx,
+        run.options.personalMode !== true,
       )
     : { toDelete: [], toTombstone: [], refusedStale: [] };
   const decommissionPlan =
@@ -1139,7 +1162,7 @@ async function executeUploads(
       // Emitting it as `type: "error"` pushed it into the runner's `errors[]`,
       // so every watch pass returned exit 2 and the menubar reported an
       // "auto-sync watcher exited unexpectedly (code=Some(2))" crash on every
-      // tick (the fleet-wide HQ-SYNC-4 flood). Surface it for visibility, but
+      // tick (the HQ-SYNC-4 flood across user machines). Surface it for visibility, but
       // do not let it flip the pass to a non-zero exit.
       let bytes = 0;
       try {
@@ -1676,6 +1699,10 @@ function defaultConsoleLogger(event: SyncProgressEvent): void {
       `    Sample refused paths: ${event.samplePaths.slice(0, 5).join(", ")}${event.samplePaths.length > 5 ? ", …" : ""}\n` +
       `    To proceed anyway: re-run with HQ_SYNC_DELETE_BULK_OVERRIDE=1 (or propagateDeletePolicy:"all").`,
     );
+  } else if (event.type === "skip-invalid-scoped-key") {
+    console.warn(
+      `  ! ${event.path} skipped — 'companies/'-prefixed key is invalid in a company-scoped vault (stale doubled local tree? remove the inner companies/<slug> copy)`,
+    );
   } else if (event.type === "ignore-excluded") {
     // The "not silent" surface: an ignore rule dropped content that doesn't
     // look like expected build/VCS/cache noise, so it never reached the vault.
@@ -2178,6 +2205,11 @@ async function computeDeletePlan(
   shouldSync: (filePath: string, isDir?: boolean) => boolean,
   policy: "currency-gated" | "owned-only" | "all",
   ctx: EntityContext,
+  // True for a COMPANY-scoped push (personalMode !== true): the sync root is
+  // the company folder and journal keys are bucket-relative, so a literal
+  // `companies/…` key is scope-invalid (see the poisoned-key branch below).
+  // Personal-vault pushes legitimately journal `companies/{slug}/…` keys.
+  companyScoped: boolean = true,
 ): Promise<DeletePlan> {
   const plan: DeletePlan = { toDelete: [], toTombstone: [], refusedStale: [] };
   if (scopeRoots.length === 0) return plan;
@@ -2249,6 +2281,20 @@ async function computeDeletePlan(
       continue;
     }
 
+    // Scope-invalid journal keys (incident 2026-07-11): in a COMPANY-scoped
+    // context, a journal entry at a literal `companies/…` key records a
+    // doubled-tree poisoning upload. HEAD/DeleteObject on such a key via the
+    // presign transport is rejected by the server validator
+    // (INVALID_KEY_COMPANIES_SCOPED) and would error the push, so route it
+    // straight to `toTombstone` (journal drop, no remote call) — the local
+    // journal entry drains; server-side cleanup of any poisoned object is an
+    // operator action. Personal-vault pushes (personalMode) carry legitimate
+    // `companies/{slug}/…` keys and are unaffected (companyScoped=false).
+    if (companyScoped && relativeKey.startsWith("companies/")) {
+      plan.toTombstone.push(relativeKey);
+      continue;
+    }
+
     if (!shouldSync(localPath, false) && !shouldSync(localPath, true)) continue;
     // Ephemeral artifacts (conflict mirrors) never propagate-delete via the
     // normal path — see EPHEMERAL_PATH_PATTERN doc. NOTE: this is a no-op