@indigoai-us/hq-cloud 6.10.2 → 6.11.1

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

@@ -21,6 +21,7 @@ import {
   buildTargetedPushArgv,
   resolvePullScope,
   readPinnedPrefixes,
+  defaultCollectTelemetry,
 } from "./sync-runner.js";
 import type {
   RunnerEvent,
@@ -3987,3 +3988,115 @@ describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", ()
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// defaultCollectTelemetry — person-entity gate (Sentry HQ-4N regression)
+//
+// The telemetry passes reject SERVER-side with a captured `no-person-entity`
+// 4xx (and a Sentry warning) when the caller has no person entity. The gate
+// skips telemetry for unprovisioned callers so the premature `/v1/usage/*`
+// (and `/v1/skill-invocations`) calls — and therefore the warnings — stop.
+// `getTelemetryOptIn()` is the first call of BOTH passes, so its call count is
+// the differential signal for "did telemetry run".
+// ---------------------------------------------------------------------------
+
+describe("defaultCollectTelemetry person-entity gate", () => {
+  function makeTelemetryClient(persons: EntityInfo[]) {
+    const calls = {
+      listByType: 0,
+      getTelemetryOptIn: 0,
+      postUsage: 0,
+      postSkillInvocations: 0,
+    };
+    const client = {
+      entity: {
+        get: async () => ({}) as unknown as EntityInfo,
+        listByType: async (_type: string) => {
+          calls.listByType++;
+          return persons;
+        },
+      },
+      // Telemetry surface (cast-to internally by defaultCollectTelemetry). With
+      // opt-in disabled, the collectors return right after this one probe, so
+      // postUsage/postSkillInvocations are never reached even when the gate
+      // lets telemetry run — getTelemetryOptIn is the clean call-ran signal.
+      getTelemetryOptIn: async () => {
+        calls.getTelemetryOptIn++;
+        return { enabled: false };
+      },
+      postUsage: async () => {
+        calls.postUsage++;
+        return { ok: true } as unknown;
+      },
+      postSkillInvocations: async () => {
+        calls.postSkillInvocations++;
+        return { written: 0, skipped: [] } as unknown;
+      },
+    };
+    return { client, calls };
+  }
+
+  const PERSON: EntityInfo = {
+    uid: "prs_abc123",
+    type: "person",
+    slug: "me",
+    status: "active",
+    bucketName: "hq-vault-prs_abc123",
+    createdAt: "2026-01-01T00:00:00Z",
+  } as unknown as EntityInfo;
+
+  it("skips both telemetry passes when the caller owns no person entity (no premature /v1/usage call)", async () => {
+    const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-tele-noperson-"));
+    try {
+      const { client, calls } = makeTelemetryClient([]); // unprovisioned caller
+      await defaultCollectTelemetry(
+        client as unknown as VaultClientSurface,
+        false,
+        hqRoot,
+      );
+      expect(calls.listByType).toBe(1); // orphan-safe probe ran
+      expect(calls.getTelemetryOptIn).toBe(0); // collectors never ran
+      expect(calls.postUsage).toBe(0);
+      expect(calls.postSkillInvocations).toBe(0);
+    } finally {
+      fs.rmSync(hqRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("runs telemetry when a canonical person entity exists (behaviour preserved for provisioned callers)", async () => {
+    const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-tele-person-"));
+    try {
+      const { client, calls } = makeTelemetryClient([PERSON]);
+      await defaultCollectTelemetry(
+        client as unknown as VaultClientSurface,
+        false,
+        hqRoot,
+      );
+      expect(calls.listByType).toBe(1);
+      // Both passes reach their opt-in probe → telemetry ran as before.
+      expect(calls.getTelemetryOptIn).toBeGreaterThan(0);
+    } finally {
+      fs.rmSync(hqRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("fails open: a thrown person probe still lets telemetry run (no provisioned-user regression)", async () => {
+    const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-tele-throw-"));
+    try {
+      const { client, calls } = makeTelemetryClient([]);
+      client.entity.listByType = async () => {
+        calls.listByType++;
+        throw new Error("transient network blip");
+      };
+      await defaultCollectTelemetry(
+        client as unknown as VaultClientSurface,
+        false,
+        hqRoot,
+      );
+      expect(calls.listByType).toBe(1);
+      expect(calls.getTelemetryOptIn).toBeGreaterThan(0); // fell through to telemetry
+    } finally {
+      fs.rmSync(hqRoot, { recursive: true, force: true });
+    }
+  });
+});

package/src/bin/sync-runner.ts

@@ -764,13 +764,42 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
 // swallowed — telemetry must never abort or delay sync.
 // ---------------------------------------------------------------------------
 
-async function defaultCollectTelemetry(
+export async function defaultCollectTelemetry(
   client: VaultClientSurface,
   clientIsStub: boolean,
   hqRoot: string,
 ): Promise<void> {
   if (clientIsStub) return;
 
+  // Person-entity gate (the "onboarding gate" the telemetry call-site must
+  // sit behind). Both telemetry passes below resolve the caller's `personUid`
+  // SERVER-side from the JWT and reject with a 4xx when the caller has not yet
+  // been provisioned a person entity: `getTelemetryOptIn()` (the first call of
+  // each pass) hits `GET /v1/usage/opt-in`, which 404s `no-person-entity` for
+  // an unprovisioned caller, and the skill pass's `POST /v1/skill-invocations`
+  // does the same. hq-pro logs every such reject as a Sentry *warning*, so an
+  // unprovisioned-but-signed-in identity that runs telemetry on a loop — e.g.
+  // a machine/daemon/outpost identity, or a single-company sync that fabricates
+  // its membership and never runs the onboarding gate — emits a steady stream
+  // of benign `no-person-entity` warnings (Sentry HQ-4N). The reject itself is
+  // harmless (telemetry is best-effort and the response is swallowed), but the
+  // noise is not. Probe the caller's OWN person entity with the orphan-safe
+  // `entity.listByType("person")` — `GET /entity/by-type/person` returns `200`
+  // with an empty list for an unprovisioned caller (no reject, no warning),
+  // and a non-empty result is the EXACT predicate for "the server will resolve
+  // a personUid" (same caller-owned-person union the usage handler's
+  // `getEffectivePersonUid` uses). Skip both passes when there is none. The
+  // probe is the same canonical-person check the runner already uses to pick
+  // the personal-vault target. Fail OPEN: a thrown probe (transient/network)
+  // falls through to run telemetry as before, so a provisioned user's
+  // telemetry is never dropped by a flaky probe.
+  try {
+    const persons = await client.entity.listByType("person");
+    if (pickCanonicalPersonEntity(persons) === null) return;
+  } catch {
+    // Probe failed — preserve prior behavior and let telemetry run.
+  }
+
   // machineId: hq-cloud owns provisioning via `<hqRoot>/.hq/machine-id`
   // (see `src/lib/machine-id.ts`). The resolver migrates forward from
   // any legacy `~/.hq/menubar.json` value on first call, then becomes

package/src/cli/sync.test.ts

@@ -69,9 +69,25 @@ const mockVendResponse = {
   expiresAt: new Date(Date.now() + 15 * 60 * 1000).toISOString(),
 };
 
-function setupFetchMock() {
+function setupFetchMock(
+  opts: { tombstones?: Array<{ key: string; deletedAt: string }> } = {},
+) {
   const fetchMock = vi.fn().mockImplementation(async (url: string) => {
     const urlStr = String(url);
+    // FILE_TOMBSTONE read surface (delete-resync). Defaults to an empty list so
+    // every legacy test exercises the no-suppression path; tests that need
+    // suppression pass `{ tombstones }`.
+    if (urlStr.includes("/v1/files/tombstones")) {
+      return {
+        ok: true,
+        status: 200,
+        json: async () => ({
+          companyUid: mockEntity.uid,
+          tombstones: opts.tombstones ?? [],
+        }),
+        text: async () => "",
+      };
+    }
     // New per-user-namespace slug resolver (hq-pro PR 67). Returns the
     // mockEntity's uid as the in-namespace match; the caller then
     // re-fetches it via `/entity/{uid}`, which is matched by the
@@ -1049,6 +1065,230 @@ describe("sync", () => {
     expect(journal.files["docs/really-deleted.md"]).toBeUndefined();
   });
 
+  // ── delete-resync: FILE_TOMBSTONE suppression (issue [6]) ──────────────────
+  // These four cover the brief's regression contract: a scoped-delete tombstone
+  // makes a delete STICK across a pull even when the object is still in the
+  // remote LIST (a peer re-pushed it / the delete-marker hasn't propagated),
+  // while a genuine re-create still syncs and a post-tombstone local edit is
+  // never silently destroyed.
+
+  it("delete-resync: a tombstoned key present in the remote LIST is removed locally and NOT re-downloaded", async () => {
+    // The core stays-deleted assertion. A peer ran `hq files delete docs/` (the
+    // scoped-delete path), which wrote a FILE_TOMBSTONE. This machine still
+    // holds the file and the object is still visible in the remote LIST (a peer
+    // re-push, or an un-propagated delete-marker). Pre-fix the planner saw
+    // "remote present, local present, unchanged" and KEPT it; worse, on a fresh
+    // machine "remote present, local absent" re-DOWNLOADED it — the resurrection
+    // loop. Now the FILE_TOMBSTONE (newer than the remote object) is
+    // authoritative: delete locally, drop the journal entry, never download.
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(path.join(companyRoot, "docs"), { recursive: true });
+    const sharedPath = path.join(companyRoot, "docs", "shared.md");
+    fs.writeFileSync(sharedPath, "shared content");
+    const crypto = await import("node:crypto");
+    const baseline = crypto
+      .createHash("sha256")
+      .update("shared content")
+      .digest("hex");
+    const now = Date.now();
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date(now - 120_000).toISOString(),
+        files: {
+          "docs/shared.md": {
+            hash: baseline,
+            size: 14,
+            syncedAt: new Date(now - 120_000).toISOString(),
+            direction: "down",
+            remoteEtag: "remote-old",
+          },
+        },
+      }),
+    );
+    // Remote object is the STALE deleted version: lastModified BEFORE the
+    // tombstone, still present in the LIST.
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      {
+        key: "docs/shared.md",
+        size: 14,
+        lastModified: new Date(now - 60_000),
+        etag: '"remote-old"',
+      },
+    ]);
+    // FILE_TOMBSTONE deleted AFTER the remote object's lastModified.
+    setupFetchMock({
+      tombstones: [
+        { key: "docs/shared.md", deletedAt: new Date(now).toISOString() },
+      ],
+    });
+
+    const result = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+
+    // Stays deleted locally …
+    expect(fs.existsSync(sharedPath)).toBe(false);
+    // … and was NEVER re-downloaded (no download, no conflict-probe download).
+    expect(s3Module.downloadFile).not.toHaveBeenCalled();
+    expect(result.filesDownloaded).toBe(0);
+    expect(result.filesTombstoned).toBeGreaterThanOrEqual(1);
+    // Journal entry dropped so it converges (no re-tombstone next run).
+    const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+    expect(journal.files["docs/shared.md"]).toBeUndefined();
+  });
+
+  it("delete-resync: a re-created object NEWER than the tombstone DOES sync (tombstone is not permanent)", async () => {
+    // The tombstone must not permanently suppress a key. After a delete, a user
+    // writes a brand-new object at the same path; its lastModified post-dates
+    // the tombstone, so it is a genuine re-create and must download normally.
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(path.join(companyRoot, "docs"), { recursive: true });
+    const recreatedPath = path.join(companyRoot, "docs", "recreated.md");
+    const now = Date.now();
+    // Empty journal + absent local: the file was deleted earlier; this is a
+    // fresh re-create arriving from the vault.
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({ version: "1", lastSync: new Date(now).toISOString(), files: {} }),
+    );
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      {
+        key: "docs/recreated.md",
+        size: 17,
+        lastModified: new Date(now), // newer than the tombstone below
+        etag: '"remote-new"',
+      },
+    ]);
+    setupFetchMock({
+      tombstones: [
+        {
+          key: "docs/recreated.md",
+          deletedAt: new Date(now - 3_600_000).toISOString(), // an hour ago
+        },
+      ],
+    });
+
+    const result = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+
+    // Re-create wins: downloaded, present locally, not tombstoned.
+    expect(s3Module.downloadFile).toHaveBeenCalled();
+    expect(fs.existsSync(recreatedPath)).toBe(true);
+    expect(result.filesDownloaded).toBeGreaterThanOrEqual(1);
+    expect(result.filesTombstoned).toBe(0);
+  });
+
+  it("delete-resync: a local edit made after the tombstone surfaces a CONFLICT, not a silent delete", async () => {
+    // Safety guard: the authoritative delete must never destroy unsynced local
+    // work. This machine edited the file locally (diverged from the synced
+    // baseline) and only then learned of the tombstone — surface a conflict and
+    // PRESERVE local, rather than unlinking it.
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(path.join(companyRoot, "docs"), { recursive: true });
+    const editedPath = path.join(companyRoot, "docs", "edited.md");
+    fs.writeFileSync(editedPath, "my local edits");
+    const crypto = await import("node:crypto");
+    const baseline = crypto
+      .createHash("sha256")
+      .update("original synced content")
+      .digest("hex");
+    const now = Date.now();
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date(now - 120_000).toISOString(),
+        files: {
+          "docs/edited.md": {
+            hash: baseline, // local has since diverged → localChanged
+            size: 23,
+            syncedAt: new Date(now - 120_000).toISOString(),
+            direction: "down",
+            remoteEtag: "remote-old",
+          },
+        },
+      }),
+    );
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      {
+        key: "docs/edited.md",
+        size: 23,
+        lastModified: new Date(now - 60_000),
+        etag: '"remote-old"',
+      },
+    ]);
+    setupFetchMock({
+      tombstones: [
+        { key: "docs/edited.md", deletedAt: new Date(now).toISOString() },
+      ],
+    });
+
+    const result = await sync({
+      company: "acme",
+      onConflict: "keep",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+
+    // Conflict surfaced; local edits preserved; nothing tombstoned away.
+    expect(result.conflicts).toBeGreaterThanOrEqual(1);
+    expect(result.conflictPaths).toContain("docs/edited.md");
+    expect(fs.existsSync(editedPath)).toBe(true);
+    expect(fs.readFileSync(editedPath, "utf-8")).toBe("my local edits");
+    expect(result.filesTombstoned).toBe(0);
+  });
+
+  it("delete-resync: suppression is per-key and the fetch is company-scoped (no cross-tenant bleed)", async () => {
+    // Two guards in one: (a) a tombstone for `docs/a.md` must NOT suppress a
+    // different key `docs/b.md` — suppression is keyed exactly; (b) the
+    // tombstone fetch is scoped to the ACTIVE company's uid, so a sync for one
+    // company never consults another company's tombstones (the client half of
+    // the cross-tenant isolation the server enforces via the
+    // FILE_TOMBSTONE#<companyUid># begins_with query).
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(path.join(companyRoot, "docs"), { recursive: true });
+    const now = Date.now();
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({ version: "1", lastSync: new Date(now).toISOString(), files: {} }),
+    );
+    // a.md = stale tombstoned version (suppressed); b.md = a normal new file.
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: "docs/a.md", size: 10, lastModified: new Date(now - 60_000), etag: '"a-old"' },
+      { key: "docs/b.md", size: 10, lastModified: new Date(now), etag: '"b-new"' },
+    ]);
+    const fetchMock = setupFetchMock({
+      tombstones: [
+        { key: "docs/a.md", deletedAt: new Date(now).toISOString() },
+      ],
+    });
+
+    const result = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+
+    // a.md suppressed (never downloaded); b.md downloaded normally.
+    expect(fs.existsSync(path.join(companyRoot, "docs", "a.md"))).toBe(false);
+    expect(fs.existsSync(path.join(companyRoot, "docs", "b.md"))).toBe(true);
+    expect(result.filesDownloaded).toBe(1);
+
+    // The tombstone read was scoped to THIS company's uid.
+    const tombstoneCall = fetchMock.mock.calls.find((c) =>
+      String(c[0]).includes("/v1/files/tombstones"),
+    );
+    expect(tombstoneCall).toBeDefined();
+    expect(String(tombstoneCall![0])).toContain(`company=${mockEntity.uid}`);
+  });
+
   it("does NOT tombstone keys when HEAD returns AccessDenied (Codex P1 — defensive STS skip)", async () => {
     // Same Codex P1, AccessDenied branch: a guest STS session may deny
     // both LIST and HEAD on out-of-scope keys. The tombstone planner