@indigoai-us/hq-cloud 5.1.8 → 5.1.10

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

@@ -15,7 +15,11 @@ import type {
   VaultClientSurface,
 } from "./sync-runner.js";
 import type { SyncResult, SyncOptions } from "../cli/sync.js";
-import type { Membership, EntityInfo } from "../vault-client.js";
+import type {
+  Membership,
+  EntityInfo,
+  PendingInviteByEmail,
+} from "../vault-client.js";
 import { VaultAuthError } from "../vault-client.js";
 
 // ---------------------------------------------------------------------------
@@ -70,11 +74,31 @@ function makeVaultStub(
   opts: {
     memberships?: Array<Pick<Membership, "companyUid">>;
     entityGet?: (uid: string) => Promise<EntityInfo>;
+    pendingInvites?: Array<Record<string, unknown>>;
+    ensurePerson?: (hints: {
+      ownerSub: string;
+      displayName: string;
+    }) => Promise<EntityInfo>;
+    claim?: (personUid: string) => Promise<void>;
   } = {},
 ): VaultClientSurface {
   const memberships = opts.memberships ?? [];
+  const pending = opts.pendingInvites ?? [];
   return {
     listMyMemberships: () => Promise.resolve(memberships as Membership[]),
+    listMyPendingInvitesByEmail: () =>
+      Promise.resolve(pending as unknown as PendingInviteByEmail[]),
+    claimPendingInvitesByEmail:
+      opts.claim ?? (() => Promise.resolve(undefined)),
+    ensureMyPersonEntity:
+      opts.ensurePerson ??
+      (() =>
+        Promise.resolve({
+          uid: "ent_person_default",
+          type: "person",
+          slug: "default-person",
+          status: "active",
+        } as unknown as EntityInfo)),
     entity: {
       get:
         opts.entityGet ??
@@ -181,12 +205,9 @@ describe("auth", () => {
   it("emits auth-error when VaultAuthError thrown during discovery", async () => {
     const deps = makeDeps({
       createVaultClient: () => ({
+        ...makeVaultStub(),
         listMyMemberships: () =>
           Promise.reject(new VaultAuthError("token expired")),
-        entity: {
-          get: (uid: string) =>
-            Promise.resolve({ uid, slug: uid } as unknown as EntityInfo),
-        },
       }),
     });
     const code = await runRunner(["--companies"], deps);
@@ -199,11 +220,8 @@ describe("auth", () => {
   it("emits error event and returns 1 on non-auth discovery failure", async () => {
     const deps = makeDeps({
       createVaultClient: () => ({
+        ...makeVaultStub(),
         listMyMemberships: () => Promise.reject(new Error("network down")),
-        entity: {
-          get: (uid: string) =>
-            Promise.resolve({ uid, slug: uid } as unknown as EntityInfo),
-        },
       }),
     });
     const code = await runRunner(["--companies"], deps);
@@ -218,6 +236,150 @@ describe("auth", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// claim-dance (first sign-in)
+// ---------------------------------------------------------------------------
+
+describe("claim-dance", () => {
+  const claims = {
+    sub: "sub-abc",
+    email: "stefan@getindigo.ai",
+    name: "Stefan Johnson",
+  };
+
+  it("claims pending invites + ensures person before listing memberships", async () => {
+    const ensureSpy = vi.fn().mockResolvedValue({
+      uid: "ent_person_stefan",
+      type: "person",
+      slug: "stefan-johnson",
+      status: "active",
+    });
+    const claimSpy = vi.fn().mockResolvedValue(undefined);
+    // First listMyMemberships returns the just-claimed row.
+    let listCalls = 0;
+    const stub = makeVaultStub({
+      pendingInvites: [
+        {
+          membershipKey: "inv_1",
+          companyUid: "cmp_indigo",
+          role: "owner",
+          invitedBy: "sub-admin",
+          invitedAt: "2026-04-20T00:00:00Z",
+        },
+      ],
+      ensurePerson: ensureSpy as unknown as VaultClientSurface["ensureMyPersonEntity"],
+      claim: claimSpy as unknown as VaultClientSurface["claimPendingInvitesByEmail"],
+    });
+    stub.listMyMemberships = () => {
+      listCalls++;
+      return Promise.resolve([{ companyUid: "cmp_indigo" }] as Membership[]);
+    };
+
+    const deps = makeDeps({
+      createVaultClient: () => stub,
+      getIdTokenClaims: () => claims,
+    });
+    const code = await runRunner(["--companies"], deps);
+    expect(code).toBe(0);
+    expect(ensureSpy).toHaveBeenCalledWith({
+      ownerSub: "sub-abc",
+      displayName: "Stefan Johnson",
+    });
+    expect(claimSpy).toHaveBeenCalledWith("ent_person_stefan");
+    expect(listCalls).toBe(1);
+    // setup-needed must NOT fire — the user has memberships after the claim.
+    expect(deps.stdout.events().some((e) => e.type === "setup-needed")).toBe(
+      false,
+    );
+  });
+
+  it("skips ensurePerson + claim when no pending invites exist", async () => {
+    const ensureSpy = vi.fn();
+    const claimSpy = vi.fn();
+    const deps = makeDeps({
+      createVaultClient: () =>
+        makeVaultStub({
+          pendingInvites: [],
+          ensurePerson:
+            ensureSpy as unknown as VaultClientSurface["ensureMyPersonEntity"],
+          claim: claimSpy as unknown as VaultClientSurface["claimPendingInvitesByEmail"],
+        }),
+      getIdTokenClaims: () => claims,
+    });
+    const code = await runRunner(["--companies"], deps);
+    expect(code).toBe(0);
+    expect(ensureSpy).not.toHaveBeenCalled();
+    expect(claimSpy).not.toHaveBeenCalled();
+    // No memberships, no invites — truly empty → setup-needed is correct here.
+    expect(deps.stdout.events()).toEqual([{ type: "setup-needed" }]);
+  });
+
+  it("skips claim-dance entirely when no idToken claims are available", async () => {
+    const pendingSpy = vi.fn().mockResolvedValue([]);
+    const stub = makeVaultStub();
+    stub.listMyPendingInvitesByEmail =
+      pendingSpy as unknown as VaultClientSurface["listMyPendingInvitesByEmail"];
+    const deps = makeDeps({
+      createVaultClient: () => stub,
+      getIdTokenClaims: () => null,
+    });
+    await runRunner(["--companies"], deps);
+    expect(pendingSpy).not.toHaveBeenCalled();
+  });
+
+  it("does not fail the run when claim-dance throws (best-effort)", async () => {
+    const stub = makeVaultStub({
+      memberships: [{ companyUid: "cmp_a" }],
+    });
+    stub.listMyPendingInvitesByEmail = () =>
+      Promise.reject(new Error("vault 500"));
+    const deps = makeDeps({
+      createVaultClient: () => stub,
+      getIdTokenClaims: () => claims,
+    });
+    const code = await runRunner(["--companies"], deps);
+    expect(code).toBe(0);
+    // Sync proceeds as usual for the existing membership.
+    expect(deps.sync).toHaveBeenCalledTimes(1);
+    expect(deps.stderr.raw()).toContain("claim-dance skipped");
+  });
+
+  it("falls back to given_name + family_name when name claim is absent", async () => {
+    const ensureSpy = vi.fn().mockResolvedValue({
+      uid: "ent_person_x",
+      type: "person",
+      slug: "x",
+      status: "active",
+    });
+    const deps = makeDeps({
+      createVaultClient: () =>
+        makeVaultStub({
+          pendingInvites: [
+            {
+              membershipKey: "inv_1",
+              companyUid: "cmp_x",
+              role: "owner",
+              invitedBy: "sub-admin",
+              invitedAt: "2026-04-20T00:00:00Z",
+            },
+          ],
+          ensurePerson:
+            ensureSpy as unknown as VaultClientSurface["ensureMyPersonEntity"],
+        }),
+      getIdTokenClaims: () => ({
+        sub: "sub-xyz",
+        given_name: "Ada",
+        family_name: "Lovelace",
+      }),
+    });
+    await runRunner(["--companies"], deps);
+    expect(ensureSpy).toHaveBeenCalledWith({
+      ownerSub: "sub-xyz",
+      displayName: "Ada Lovelace",
+    });
+  });
+});
+
 // ---------------------------------------------------------------------------
 // target resolution
 // ---------------------------------------------------------------------------
@@ -236,11 +398,11 @@ describe("target resolution", () => {
     const listSpy = vi.fn();
     const deps = makeDeps({
       createVaultClient: () => ({
-        listMyMemberships: listSpy as unknown as () => Promise<Membership[]>,
-        entity: {
-          get: (uid: string) =>
+        ...makeVaultStub({
+          entityGet: (uid: string) =>
             Promise.resolve({ uid, slug: "acme" } as unknown as EntityInfo),
-        },
+        }),
+        listMyMemberships: listSpy as unknown as () => Promise<Membership[]>,
       }),
     });
     const code = await runRunner(["--company", "cmp_abc"], deps);
@@ -303,6 +465,31 @@ describe("fanout-plan", () => {
     expect(plan.companies).toEqual([{ uid: "cmp_ghost", slug: "cmp_ghost" }]);
   });
 
+  it("includes entity.name on plan entries when available", async () => {
+    const deps = makeDeps({
+      createVaultClient: () =>
+        makeVaultStub({
+          memberships: [{ companyUid: "cmp_a" }, { companyUid: "cmp_b" }],
+          entityGet: (uid: string) =>
+            Promise.resolve({
+              uid,
+              slug: uid === "cmp_a" ? "acme" : "beta",
+              name: uid === "cmp_a" ? "Acme Corp" : undefined,
+            } as unknown as EntityInfo),
+        }),
+    });
+
+    const code = await runRunner(["--companies"], deps);
+    expect(code).toBe(0);
+    const plan = deps.stdout
+      .events()
+      .find((e) => e.type === "fanout-plan") as Extract<RunnerEvent, { type: "fanout-plan" }>;
+    expect(plan.companies).toEqual([
+      { uid: "cmp_a", slug: "acme", name: "Acme Corp" },
+      { uid: "cmp_b", slug: "beta" },
+    ]);
+  });
+
   it("degrades to UID when entity.get returns falsy slug", async () => {
     const deps = makeDeps({
       createVaultClient: () =>

package/src/bin/sync-runner.ts

@@ -38,12 +38,15 @@ import * as fs from "fs";
 import { fileURLToPath } from "url";
 import {
   getValidAccessToken,
+  loadCachedTokens,
   VaultClient,
   VaultAuthError,
   type CognitoAuthConfig,
+  type CognitoTokens,
   type VaultServiceConfig,
   type Membership,
   type EntityInfo,
+  type PendingInviteByEmail,
 } from "../index.js";
 import { sync as defaultSync } from "../cli/sync.js";
 import type {
@@ -90,7 +93,7 @@ export type RunnerEvent =
   | { type: "auth-error"; message: string }
   | {
       type: "fanout-plan";
-      companies: Array<{ uid: string; slug: string }>;
+      companies: Array<{ uid: string; slug: string; name?: string }>;
     }
   | ({ type: "progress"; company: string } & Omit<Extract<SyncProgressEvent, { type: "progress" }>, "type">)
   | ({ type: "error"; company?: string } & Omit<Extract<SyncProgressEvent, { type: "error" }>, "type">)
@@ -113,11 +116,26 @@ export type RunnerEvent =
  */
 export interface VaultClientSurface {
   listMyMemberships: () => Promise<Membership[]>;
+  listMyPendingInvitesByEmail: () => Promise<PendingInviteByEmail[]>;
+  claimPendingInvitesByEmail: (personUid: string) => Promise<void>;
+  ensureMyPersonEntity: (hints: {
+    ownerSub: string;
+    displayName: string;
+  }) => Promise<EntityInfo>;
   entity: {
     get: (uid: string) => Promise<EntityInfo>;
   };
 }
 
+/** Minimal shape of the claims we read off the Cognito idToken. */
+interface IdTokenClaims {
+  sub?: string;
+  email?: string;
+  name?: string;
+  given_name?: string;
+  family_name?: string;
+}
+
 export interface RunnerDeps {
   /** Where to write ndjson events. Defaults to `process.stdout`. */
   stdout?: { write: (chunk: string) => boolean | void };
@@ -125,16 +143,93 @@ export interface RunnerDeps {
   stderr?: { write: (chunk: string) => boolean | void };
   /** Resolve a valid access token. Defaults to `getValidAccessToken` non-interactive. */
   getAccessToken?: () => Promise<string>;
+  /**
+   * Read the caller's identity claims (sub/email/name) off the cached Cognito
+   * idToken. Defaults to decoding `loadCachedTokens().idToken`. Returns `null`
+   * when no cached tokens exist — the runner will then skip the claim-dance
+   * and fall through to the usual listMyMemberships path.
+   */
+  getIdTokenClaims?: () => IdTokenClaims | null;
   /**
    * Produce a VaultClient-like object. Defaults to `new VaultClient(config)`.
-   * Tests inject a stub here — only `listMyMemberships` and `entity.get` are
-   * called by the runner, so stubs only need to implement those.
+   * Tests inject a stub here — the runner only calls the methods listed in
+   * `VaultClientSurface`.
    */
   createVaultClient?: (config: VaultServiceConfig) => VaultClientSurface;
   /** Sync function. Defaults to `cli/sync.sync`. */
   sync?: (options: SyncOptions) => Promise<SyncResult>;
 }
 
+// ---------------------------------------------------------------------------
+// JWT claim decoder — inlined to avoid pulling a dep just to read an idToken.
+// We do NOT verify the signature here — Cognito already did that when it
+// issued the token, and we only read the public claims (sub/email/name) to
+// drive the claim-dance + create the person entity. If the token is tampered
+// with, the downstream vault-service call will reject it (signature-verified
+// there) long before any claimed value causes harm.
+// ---------------------------------------------------------------------------
+
+function decodeJwtClaims(jwt: string): IdTokenClaims | null {
+  const parts = jwt.split(".");
+  if (parts.length !== 3) return null;
+  try {
+    const payload = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const padded = payload + "=".repeat((4 - (payload.length % 4)) % 4);
+    const json = Buffer.from(padded, "base64").toString("utf-8");
+    return JSON.parse(json) as IdTokenClaims;
+  } catch {
+    return null;
+  }
+}
+
+function defaultGetIdTokenClaims(): IdTokenClaims | null {
+  const tokens: CognitoTokens | null = loadCachedTokens();
+  if (!tokens?.idToken) return null;
+  return decodeJwtClaims(tokens.idToken);
+}
+
+/**
+ * Best-effort: claim any email-keyed pending invites that were sent before
+ * this user had a person entity. Mirrors the installer's vault-handoff flow.
+ *
+ * Silent on the happy path — only logs to stderr on soft failures (so a
+ * transient network blip doesn't block the sync). Never throws: a caller who
+ * can't list memberships despite an unclaimed invite is no worse off than the
+ * pre-claim-dance behavior (which was to emit setup-needed).
+ */
+async function runClaimDance(
+  client: VaultClientSurface,
+  claims: IdTokenClaims,
+  stderr: { write: (chunk: string) => boolean | void },
+): Promise<void> {
+  try {
+    const pending = await client.listMyPendingInvitesByEmail();
+    if (pending.length === 0) return;
+
+    const displayName =
+      claims.name ??
+      [claims.given_name, claims.family_name].filter(Boolean).join(" ") ??
+      claims.email ??
+      "";
+    const ownerSub = claims.sub ?? "";
+    if (!ownerSub || !displayName) {
+      stderr.write(
+        "hq-sync-runner: skipping claim-dance — idToken missing sub/name\n",
+      );
+      return;
+    }
+
+    const person = await client.ensureMyPersonEntity({
+      ownerSub,
+      displayName,
+    });
+    await client.claimPendingInvitesByEmail(person.uid);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    stderr.write(`hq-sync-runner: claim-dance skipped — ${msg}\n`);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // argv parser — intentionally minimal (no commander/yargs dep)
 // ---------------------------------------------------------------------------
@@ -244,8 +339,20 @@ export async function runRunner(
   let memberships: Pick<Membership, "companyUid">[];
   try {
     if (parsed.companies) {
+      // Before giving up on memberships, run the claim-dance: new users signed
+      // in via the tray may have email-keyed invites waiting for them. Without
+      // this, an invited user would see "setup-needed" on every tray click.
+      const getClaims = deps.getIdTokenClaims ?? defaultGetIdTokenClaims;
+      const claims = getClaims();
+      if (claims) {
+        await runClaimDance(client, claims, stderr);
+      }
+
       memberships = await client.listMyMemberships();
       if (memberships.length === 0) {
+        // Truly empty — still a valid state (no memberships = nothing to
+        // sync). The tray will show a friendly "create your first company"
+        // CTA rather than an alarm banner.
         emit({ type: "setup-needed" });
         return 0;
       }
@@ -278,16 +385,18 @@ export async function runRunner(
   // The menubar wants "Syncing indigo" in its UI, not the raw cmp_* ULID.
   // If the entity fetch fails for some row (entity deleted, scoping issue),
   // degrade to using the UID as the slug rather than aborting the run.
-  const plan: Array<{ uid: string; slug: string }> = [];
+  const plan: Array<{ uid: string; slug: string; name?: string }> = [];
   for (const m of memberships) {
     let slug = m.companyUid;
+    let name: string | undefined;
     try {
       const info = await client.entity.get(m.companyUid);
       slug = info.slug || m.companyUid;
+      name = info.name;
     } catch {
       // Best-effort — keep UID as the display identifier.
     }
-    plan.push({ uid: m.companyUid, slug });
+    plan.push({ uid: m.companyUid, slug, ...(name ? { name } : {}) });
   }
   emit({ type: "fanout-plan", companies: plan });
 

package/src/cli/accept.ts

@@ -40,8 +40,8 @@ export function parseToken(tokenOrLink: string): string {
     return trimmed.slice("hq://accept/".length);
   }
 
-  // https://hq.indigoai.com/accept/<token> (future web route)
-  const httpsPrefix = "https://hq.indigoai.com/accept/";
+  // https://example.com/accept/<token> (future web route)
+  const httpsPrefix = "https://example.com/accept/";
   if (trimmed.startsWith(httpsPrefix)) {
     return trimmed.slice(httpsPrefix.length);
   }

package/src/cli/share.test.ts

@@ -19,7 +19,7 @@ vi.mock("../s3.js", () => ({
 }));
 
 import { share } from "./share.js";
-import { headRemoteFile } from "../s3.js";
+import { headRemoteFile, uploadFile } from "../s3.js";
 
 const mockConfig: VaultServiceConfig = {
   apiUrl: "https://vault-api.test",
@@ -82,8 +82,10 @@ describe("share", () => {
     delete process.env.HQ_STATE_DIR;
   });
 
-  it("shares a single file", async () => {
-    const testFile = path.join(tmpDir, "test.md");
+  it("shares a single file keyed relative to the company root", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const testFile = path.join(companyRoot, "test.md");
     fs.writeFileSync(testFile, "# Hello World");
 
     const result = await share({
@@ -95,15 +97,18 @@ describe("share", () => {
 
     expect(result.filesUploaded).toBe(1);
     expect(result.aborted).toBe(false);
+    // Remote key must be company-relative, not hqRoot-relative
+    expect(uploadFile).toHaveBeenCalledWith(expect.anything(), testFile, "test.md");
   });
 
   it("respects ignore rules", async () => {
-    fs.mkdirSync(path.join(tmpDir, ".git"));
-    fs.writeFileSync(path.join(tmpDir, ".git", "config"), "git config");
-    fs.writeFileSync(path.join(tmpDir, "readme.md"), "readme");
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(path.join(companyRoot, ".git"), { recursive: true });
+    fs.writeFileSync(path.join(companyRoot, ".git", "config"), "git config");
+    fs.writeFileSync(path.join(companyRoot, "readme.md"), "readme");
 
     const result = await share({
-      paths: [tmpDir],
+      paths: [companyRoot],
       company: "acme",
       vaultConfig: mockConfig,
       hqRoot: tmpDir,
@@ -113,12 +118,13 @@ describe("share", () => {
   });
 
   it("shares a directory of files", async () => {
-    fs.mkdirSync(path.join(tmpDir, "docs"));
-    fs.writeFileSync(path.join(tmpDir, "docs", "a.md"), "doc a");
-    fs.writeFileSync(path.join(tmpDir, "docs", "b.md"), "doc b");
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(path.join(companyRoot, "docs"), { recursive: true });
+    fs.writeFileSync(path.join(companyRoot, "docs", "a.md"), "doc a");
+    fs.writeFileSync(path.join(companyRoot, "docs", "b.md"), "doc b");
 
     const result = await share({
-      paths: [path.join(tmpDir, "docs")],
+      paths: [path.join(companyRoot, "docs")],
       company: "acme",
       vaultConfig: mockConfig,
       hqRoot: tmpDir,
@@ -127,6 +133,44 @@ describe("share", () => {
     expect(result.filesUploaded).toBe(2);
   });
 
+  it("keys nested paths relative to the company root, not hqRoot", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(path.join(companyRoot, "knowledge"), { recursive: true });
+    const nested = path.join(companyRoot, "knowledge", "crawl.json");
+    fs.writeFileSync(nested, "{}");
+
+    await share({
+      paths: [nested],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+
+    // Key is "knowledge/crawl.json", not "companies/acme/knowledge/crawl.json"
+    expect(uploadFile).toHaveBeenCalledWith(expect.anything(), nested, "knowledge/crawl.json");
+  });
+
+  it("skips files outside the company folder with a warning", async () => {
+    const warnSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    // File at hqRoot, outside companies/acme/
+    const outsideFile = path.join(tmpDir, "stray.md");
+    fs.writeFileSync(outsideFile, "stray");
+
+    const result = await share({
+      paths: [outsideFile],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+
+    expect(result.filesUploaded).toBe(0);
+    expect(uploadFile).not.toHaveBeenCalled();
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringMatching(/outside company folder/i),
+    );
+    warnSpy.mockRestore();
+  });
+
   it("throws when no company specified and no active company", async () => {
     fs.writeFileSync(path.join(tmpDir, "test.md"), "test");
 
@@ -140,12 +184,14 @@ describe("share", () => {
   });
 
   it("resolves active company from .hq/config.json", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
     fs.mkdirSync(path.join(tmpDir, ".hq"), { recursive: true });
     fs.writeFileSync(path.join(tmpDir, ".hq", "config.json"), JSON.stringify({ activeCompany: "acme" }));
-    fs.writeFileSync(path.join(tmpDir, "test.md"), "test");
+    fs.writeFileSync(path.join(companyRoot, "test.md"), "test");
 
     const result = await share({
-      paths: [path.join(tmpDir, "test.md")],
+      paths: [path.join(companyRoot, "test.md")],
       vaultConfig: mockConfig,
       hqRoot: tmpDir,
     });

package/src/cli/share.ts

@@ -54,6 +54,10 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
 
   // Resolve entity context (handles STS vending + caching)
   let ctx = await resolveEntityContext(companyRef, vaultConfig);
+  // Remote keys are company-relative; the on-disk scoping prefix is
+  // companies/{slug}/. Anything outside this folder gets skipped to avoid
+  // leaking cross-company state into the vault.
+  const syncRoot = path.join(hqRoot, "companies", ctx.slug);
   const shouldSync = createIgnoreFilter(hqRoot);
   const journal = readJournal(ctx.slug);
 
@@ -62,7 +66,7 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
   let filesSkipped = 0;
 
   // Collect all files to share
-  const filesToShare = collectFiles(paths, hqRoot, shouldSync);
+  const filesToShare = collectFiles(paths, hqRoot, syncRoot, shouldSync);
 
   for (const { absolutePath, relativePath } of filesToShare) {
     if (!isWithinSizeLimit(absolutePath)) {
@@ -155,10 +159,15 @@ function resolveActiveCompany(hqRoot: string): string | undefined {
 
 /**
  * Collect files from paths (expanding directories recursively).
+ *
+ * Remote S3 keys are computed relative to `syncRoot` (companies/{slug}/), not
+ * `hqRoot`. Files outside `syncRoot` are skipped with a warning — sharing
+ * anything outside a company's folder would leak state into the wrong vault.
  */
 function collectFiles(
   paths: string[],
   hqRoot: string,
+  syncRoot: string,
   filter: (p: string) => boolean,
 ): { absolutePath: string; relativePath: string }[] {
   const results: { absolutePath: string; relativePath: string }[] = [];
@@ -171,11 +180,16 @@ function collectFiles(
       continue;
     }
 
+    if (!isWithin(syncRoot, absolutePath)) {
+      console.error(`  Warning: ${p} is outside company folder, skipping.`);
+      continue;
+    }
+
     const stat = fs.statSync(absolutePath);
     if (stat.isDirectory()) {
-      results.push(...walkDir(absolutePath, hqRoot, filter));
+      results.push(...walkDir(absolutePath, syncRoot, filter));
     } else if (stat.isFile()) {
-      const relativePath = path.relative(hqRoot, absolutePath);
+      const relativePath = path.relative(syncRoot, absolutePath);
       if (filter(absolutePath)) {
         results.push({ absolutePath, relativePath });
       }
@@ -187,7 +201,7 @@ function collectFiles(
 
 function walkDir(
   dir: string,
-  root: string,
+  syncRoot: string,
   filter: (p: string) => boolean,
 ): { absolutePath: string; relativePath: string }[] {
   const results: { absolutePath: string; relativePath: string }[] = [];
@@ -199,14 +213,19 @@ function walkDir(
     if (!filter(absolutePath)) continue;
 
     if (entry.isDirectory()) {
-      results.push(...walkDir(absolutePath, root, filter));
+      results.push(...walkDir(absolutePath, syncRoot, filter));
     } else if (entry.isFile()) {
       results.push({
         absolutePath,
-        relativePath: path.relative(root, absolutePath),
+        relativePath: path.relative(syncRoot, absolutePath),
       });
     }
   }
 
   return results;
 }
+
+function isWithin(parent: string, child: string): boolean {
+  const rel = path.relative(parent, child);
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}