@indigoai-us/hq-cloud 6.14.24 → 6.14.26

package/src/telemetry.test.ts

@@ -33,24 +33,42 @@ interface StubClient extends TelemetryClientSurface {
   posts: UsageBatch[];
   /** Number of times `getTelemetryOptIn` was called. */
   optInCalls: number;
+  /** Every value handed to `setTelemetryOptIn`, in arrival order. */
+  optInSets: boolean[];
+  /** The options object passed alongside each `setTelemetryOptIn` call. */
+  optInSetOpts: Array<{ onlyIfUnset?: boolean } | undefined>;
 }
 
 function makeClient(opts: {
   optInResponse?: TelemetryOptInResponse | Error;
   postResponse?: UsageIngestResult | Error;
+  /** When set, `setTelemetryOptIn` rejects with this error. */
+  setOptInError?: Error;
+  /** `applied` value the conditional write reports back (default true). */
+  setOptInApplied?: boolean;
 } = {}): StubClient {
   const optInResponse = opts.optInResponse ?? { enabled: true, updatedAt: null };
   const postResponse = opts.postResponse ?? { ok: true, written: 0, skipped: [] };
 
   const posts: UsageBatch[] = [];
+  const optInSets: boolean[] = [];
+  const optInSetOpts: Array<{ onlyIfUnset?: boolean } | undefined> = [];
   const stub: StubClient = {
     posts,
     optInCalls: 0,
+    optInSets,
+    optInSetOpts,
     async getTelemetryOptIn() {
       this.optInCalls++;
       if (optInResponse instanceof Error) throw optInResponse;
       return optInResponse;
     },
+    async setTelemetryOptIn(enabled: boolean, setOpts?: { onlyIfUnset?: boolean }) {
+      optInSets.push(enabled);
+      optInSetOpts.push(setOpts);
+      if (opts.setOptInError) throw opts.setOptInError;
+      return { applied: opts.setOptInApplied ?? true };
+    },
     async postUsage(batch: UsageBatch) {
       posts.push(batch);
       if (postResponse instanceof Error) throw postResponse;
@@ -722,3 +740,226 @@ describe("collectAndSendTelemetry — companyUid attribution", () => {
     for (const ev of events) expect(ev.companyUid).toBe(COMPANY_UID);
   });
 });
+
+const CALLER = "prs_01CALLER";
+
+// ── Consent self-heal ────────────────────────────────────────────────────────
+//
+// Regression for the opt-in race: the installer writes the user's answer to
+// `~/.hq/menubar.json` (always succeeds) AND posts it to `/v1/usage/opt-in` —
+// but that post fires before the person entity exists, so it 404s and the
+// server attribute is never written. Absence read as `false`, the emitter went
+// silent, and the person showed as "not opted in" forever. Measured in prod:
+// 22 of 33 active Indigo members had NO attribute at all, against 2 genuine
+// opt-outs.
+//
+// The heal replays the answer the user already gave. It must fire ONLY on the
+// server's `unset` state, and must never invent or overwrite consent.
+
+describe("collectAndSendTelemetry — consent self-heal", () => {
+  let env: TestEnv;
+  beforeEach(() => {
+    env = setupEnv();
+  });
+  afterEach(() => teardownEnv(env));
+
+  // The cached answer must name the account it belongs to; an unbound record is
+  // deliberately not replayable (see the cross-account test below).
+  function writeMenubar(value: unknown, personUid: string | undefined = CALLER): void {
+    fs.writeFileSync(
+      env.menubarPath,
+      JSON.stringify({
+        telemetryEnabled: value,
+        ...(personUid ? { telemetryOptInPersonUid: personUid } : {}),
+      }),
+    );
+  }
+
+  it("re-asserts a local opt-IN when the server has no recorded consent", async () => {
+    writeMenubar(true);
+    const client = makeClient({
+      optInResponse: { enabled: false, updatedAt: null, unset: true, personUid: CALLER },
+    });
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(client.optInSets).toEqual([true]);
+    expect(result.enabled).toBe(true);
+    expect(result.optInSource).toBe("menubar-reasserted");
+  });
+
+  it("re-asserts a local opt-OUT so the server records the real answer", async () => {
+    writeMenubar(false);
+    const client = makeClient({
+      optInResponse: { enabled: false, updatedAt: null, unset: true, personUid: CALLER },
+    });
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(client.optInSets).toEqual([false]);
+    expect(result.enabled).toBe(false);
+  });
+
+  it("NEVER overwrites an explicit server opt-out", async () => {
+    // The user opted in on this machine at some point, then explicitly opted
+    // out account-wide. The account-wide answer must win.
+    writeMenubar(true);
+    const client = makeClient({
+      optInResponse: { enabled: false, updatedAt: "2026-06-19T16:11:09.939Z", unset: false },
+    });
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(client.optInSets).toEqual([]);
+    expect(result.enabled).toBe(false);
+    expect(result.optInSource).toBe("server");
+  });
+
+  it("does not invent consent when no local answer exists", async () => {
+    // No menubar.json at all — we hold no answer, so we assert nothing.
+    const client = makeClient({
+      optInResponse: { enabled: false, updatedAt: null, unset: true, personUid: CALLER },
+    });
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(client.optInSets).toEqual([]);
+    expect(result.enabled).toBe(false);
+  });
+
+  it("does not invent consent when the local value is not a boolean", async () => {
+    writeMenubar("yes");
+    const client = makeClient({
+      optInResponse: { enabled: false, updatedAt: null, unset: true, personUid: CALLER },
+    });
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(client.optInSets).toEqual([]);
+    expect(result.enabled).toBe(false);
+  });
+
+  it("falls back to the server answer when the re-assert POST fails", async () => {
+    writeMenubar(true);
+    const client = makeClient({
+      optInResponse: { enabled: false, updatedAt: null, unset: true, personUid: CALLER },
+      setOptInError: new Error("network down"),
+    });
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(client.optInSets).toEqual([true]);
+    // Non-fatal: the run completes on the server's answer and retries next time.
+    expect(result.enabled).toBe(false);
+    expect(result.optInSource).toBe("server");
+  });
+
+  it("skips the heal entirely against an older server that omits `unset`", async () => {
+    writeMenubar(true);
+    const client = makeClient({ optInResponse: { enabled: false, updatedAt: null } });
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(client.optInSets).toEqual([]);
+    expect(result.optInSource).toBe("server");
+  });
+});
+
+// The self-heal must be ATOMIC. Reading `unset` and replaying the local answer
+// are two requests; without a server-side condition another device could record
+// a real opt-out in between and the replay would clobber it.
+describe("collectAndSendTelemetry — self-heal is conditional", () => {
+  let env: TestEnv;
+  beforeEach(() => {
+    env = setupEnv();
+  });
+  afterEach(() => teardownEnv(env));
+
+  it("asks the server to write ONLY if the consent is still unset", async () => {
+    fs.writeFileSync(
+      env.menubarPath,
+      JSON.stringify({ telemetryEnabled: true, telemetryOptInPersonUid: CALLER }),
+    );
+    const client = makeClient({
+      optInResponse: { enabled: false, updatedAt: null, unset: true, personUid: CALLER },
+    });
+
+    await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(client.optInSetOpts[0]).toMatchObject({ onlyIfUnset: true });
+  });
+
+  it("defers to the server when the conditional write loses the race", async () => {
+    // A real answer was recorded elsewhere between our GET and our POST.
+    fs.writeFileSync(
+      env.menubarPath,
+      JSON.stringify({ telemetryEnabled: true, telemetryOptInPersonUid: CALLER }),
+    );
+    const client = makeClient({
+      optInResponse: { enabled: false, updatedAt: null, unset: true, personUid: CALLER },
+      setOptInApplied: false,
+    });
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    // The stale local `true` must NOT win over the answer that landed first.
+    expect(result.enabled).toBe(false);
+    expect(result.optInSource).toBe("server");
+  });
+});
+
+// The cached consent lives in a per-MACHINE file. If two people sign in under
+// the same OS user it holds whoever answered LAST, so replaying it for a
+// different account would opt in someone who never consented.
+describe("collectAndSendTelemetry — consent replay is account-scoped", () => {
+  let env: TestEnv;
+  beforeEach(() => {
+    env = setupEnv();
+  });
+  afterEach(() => teardownEnv(env));
+
+  it("does NOT replay a cached answer belonging to a different account", async () => {
+    fs.writeFileSync(
+      env.menubarPath,
+      JSON.stringify({ telemetryEnabled: true, telemetryOptInPersonUid: "prs_01SOMEONE_ELSE" }),
+    );
+    const client = makeClient({
+      optInResponse: { enabled: false, updatedAt: null, unset: true, personUid: CALLER },
+    });
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(client.optInSets).toEqual([]);
+    expect(result.enabled).toBe(false);
+  });
+
+  it("does NOT replay a legacy record with no account binding", async () => {
+    // Written before consent was bound to an account — we cannot prove whose
+    // answer it is, so the installer's post-sign-in upload is the recovery path.
+    fs.writeFileSync(env.menubarPath, JSON.stringify({ telemetryEnabled: true }));
+    const client = makeClient({
+      optInResponse: { enabled: false, updatedAt: null, unset: true, personUid: CALLER },
+    });
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(client.optInSets).toEqual([]);
+    expect(result.enabled).toBe(false);
+  });
+
+  it("does NOT replay when the server cannot say who the caller is", async () => {
+    fs.writeFileSync(
+      env.menubarPath,
+      JSON.stringify({ telemetryEnabled: true, telemetryOptInPersonUid: CALLER }),
+    );
+    // Older server: no `personUid`, so the match cannot be proven.
+    const client = makeClient({
+      optInResponse: { enabled: false, updatedAt: null, unset: true },
+    });
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(client.optInSets).toEqual([]);
+    expect(result.enabled).toBe(false);
+  });
+});

package/src/telemetry.ts

@@ -48,6 +48,14 @@ import type {
 export interface TelemetryClientSurface {
   getTelemetryOptIn(): Promise<TelemetryOptInResponse>;
   postUsage(batch: UsageBatch): Promise<UsageIngestResult>;
+  /**
+   * Optional so an older client (or a narrow test stub) still satisfies the
+   * surface — when it is absent the consent self-heal is simply skipped.
+   */
+  setTelemetryOptIn?(
+    enabled: boolean,
+    opts?: { onlyIfUnset?: boolean },
+  ): Promise<{ applied: boolean } | void>;
 }
 
 export interface CollectTelemetryOptions {
@@ -79,7 +87,7 @@ export interface CollectTelemetryResult {
   /** Whether the opt-in check resolved to true (either server-side or via the menubar fallback). When false, nothing else ran. */
   enabled: boolean;
   /** Source for the `enabled` decision — useful for diagnosing missing-events reports. */
-  optInSource: "server" | "menubar-fallback" | "skipped";
+  optInSource: "server" | "menubar-fallback" | "menubar-reasserted" | "skipped";
   /** How many `.jsonl` files we considered (before the cursor diff). */
   filesScanned: number;
   /** Total events successfully POSTed across all batches. */
@@ -129,12 +137,58 @@ async function saveCursor(cursorPath: string, cursor: TelemetryCursor): Promise<
 // ── Local opt-in fallback ─────────────────────────────────────────────────────
 
 async function readLocalTelemetryEnabled(menubarPath: string): Promise<boolean> {
+  return (await readLocalTelemetryPreference(menubarPath)) === true;
+}
+
+/**
+ * Tri-state read of the locally-stored consent.
+ *
+ * `~/.hq/menubar.json` → `telemetryEnabled` is written by the installer the
+ * moment the user answers the prompt, and that local write ALWAYS succeeds —
+ * unlike the paired server write, which fires before the person entity exists
+ * and 404s. So this file is frequently the ONLY durable record of the user's
+ * actual choice.
+ *
+ * `undefined` means absent / unreadable / not a boolean — "we hold no answer" —
+ * as distinct from `false`, which is a real opt-out. The self-heal path must
+ * never conflate the two: it replays an answer, it does not invent one.
+ */
+async function readLocalTelemetryPreference(
+  menubarPath: string,
+): Promise<boolean | undefined> {
+  return (await readLocalConsentRecord(menubarPath)).enabled;
+}
+
+/**
+ * The locally-cached consent plus the account it belongs to.
+ *
+ * `telemetryOptInPersonUid` binds the answer to the `prs_*` that gave it.
+ * `menubar.json` is a per-MACHINE file, so when two people sign in under the
+ * same OS user it holds whoever answered LAST — replaying it unconditionally
+ * would opt in an account that never consented. The binding is what makes the
+ * replay safe; an unbound (legacy) record cannot be proven to belong to the
+ * current caller and is therefore never replayed.
+ */
+async function readLocalConsentRecord(
+  menubarPath: string,
+): Promise<{ enabled?: boolean; personUid?: string }> {
   try {
     const raw = await fs.readFile(menubarPath, "utf-8");
-    const parsed = JSON.parse(raw) as { telemetryEnabled?: unknown };
-    return parsed.telemetryEnabled === true;
+    const parsed = JSON.parse(raw) as {
+      telemetryEnabled?: unknown;
+      telemetryOptInPersonUid?: unknown;
+    };
+    return {
+      enabled:
+        typeof parsed.telemetryEnabled === "boolean" ? parsed.telemetryEnabled : undefined,
+      personUid:
+        typeof parsed.telemetryOptInPersonUid === "string" &&
+        parsed.telemetryOptInPersonUid.length > 0
+          ? parsed.telemetryOptInPersonUid
+          : undefined,
+    };
   } catch {
-    return false;
+    return {};
   }
 }
 
@@ -422,15 +476,79 @@ export async function collectAndSendTelemetry(
   // When `hqRoot` is omitted the map is empty → every event stays unattributed.
   const repoCompanyMap: RepoCompanyMap = opts.hqRoot
     ? await buildRepoCompanyMap(opts.hqRoot)
-    : { entries: [], bySlug: new Map() };
+    : { entries: [], bySlug: new Map(), foldsCase: false, ambiguous: new Set<string>() };
 
-  // 1. Opt-in check (server-authoritative, with local fallback).
+  // 1. Opt-in check (server-authoritative, with local fallback + self-heal).
   let enabled: boolean;
   let optInSource: CollectTelemetryResult["optInSource"];
   try {
     const resp = await opts.client.getTelemetryOptIn();
     enabled = resp.enabled === true;
     optInSource = "server";
+
+    // Self-heal a consent the user gave but that never reached the server.
+    //
+    // The installer writes the answer to `~/.hq/menubar.json` (always succeeds)
+    // AND posts it to `/v1/usage/opt-in` — but that post fires before the
+    // person entity exists, so it 404s and the attribute is never written.
+    // Absence then reads as `false`, the emitter goes silent, and the person
+    // shows as "not opted in" forever. Measured: 22 of 33 active Indigo members
+    // had no attribute at all, against only 2 genuine opt-outs.
+    //
+    // `unset` (never answered) is the ONLY state we heal. An explicit server
+    // `false` is a real opt-out and is left strictly alone. We also require a
+    // local answer to actually exist — we never invent consent, we only replay
+    // the answer the user already gave.
+    //
+    // And it must be THIS account's answer. `menubar.json` is per-MACHINE, so
+    // when two people sign in under the same OS user it holds whoever answered
+    // last; replaying that for the second account would opt in someone who
+    // never consented. The replay therefore requires the cached record to name
+    // the same `prs_*` the server says we are. A legacy record with no binding
+    // cannot be proven to belong to this caller and is skipped — for those
+    // machines the installer's own post-sign-in upload is the recovery path,
+    // and it is correctly account-scoped because it runs right after that
+    // person authenticates.
+    if (resp.unset === true && opts.client.setTelemetryOptIn) {
+      const record = await readLocalConsentRecord(menubarPath);
+      const local = record.enabled;
+      const boundToCaller =
+        record.personUid !== undefined &&
+        resp.personUid !== undefined &&
+        record.personUid === resp.personUid;
+      if (local !== undefined && !boundToCaller) {
+        log(
+          "[telemetry] skipping consent re-assert: the locally cached answer is not bound to the signed-in account",
+        );
+      }
+      if (local !== undefined && boundToCaller) {
+        try {
+          // `onlyIfUnset` keeps the replay atomic. Reading `unset` and writing
+          // are two requests, so without it another device could record a real
+          // opt-out in between and this stale local answer would overwrite it.
+          // The server tests "still unset?" as part of the write instead.
+          const ack = await opts.client.setTelemetryOptIn(local, { onlyIfUnset: true });
+          if (ack && ack.applied === false) {
+            // Lost the race — a real answer was recorded first and it stands.
+            // Keep the server's answer for this run rather than the local one.
+            log(
+              "[telemetry] consent was recorded elsewhere before the re-assert landed; deferring to the server",
+            );
+          } else {
+            enabled = local;
+            optInSource = "menubar-reasserted";
+            log(
+              `[telemetry] server had no recorded consent; re-asserted the local install-time answer (enabled=${local})`,
+            );
+          }
+        } catch (err) {
+          // Non-fatal: fall through on the server's answer. Next run retries.
+          log(
+            `[telemetry] failed to re-assert local opt-in (${(err as Error).message ?? err})`,
+          );
+        }
+      }
+    }
   } catch (err) {
     log(`[telemetry] opt-in check failed (${(err as Error).message ?? err}) — falling back to local menubar.json`);
     enabled = await readLocalTelemetryEnabled(menubarPath);

package/src/vault-client.ts

@@ -414,6 +414,25 @@ export interface VendChildResult {
 export interface TelemetryOptInResponse {
   enabled: boolean;
   updatedAt: string | null;
+  /**
+   * `true` when the person row carries NO `telemetryOptIn` attribute — i.e. the
+   * consent question has never been answered server-side. Distinct from
+   * `enabled: false`, which is a deliberate opt-OUT.
+   *
+   * Optional because older servers omit it entirely. Absent is treated as
+   * `false`, so a client talking to one behaves exactly as before — no
+   * self-heal, no surprise writes.
+   */
+  unset?: boolean;
+  /**
+   * The `prs_*` uid this answer belongs to — i.e. the authenticated caller.
+   *
+   * Needed because the local consent cache is a per-MACHINE file: if two people
+   * sign in under the same OS user it holds whoever answered last. A client
+   * must not replay it for a different account. Optional (older servers omit
+   * it), and absence means the replay cannot be proven safe, so it is skipped.
+   */
+  personUid?: string;
 }
 
 export interface UsageBatch {
@@ -637,9 +656,26 @@ const telemetryOptInResponseSchema: VaultResponseSchema<TelemetryOptInResponse>
     .object({
       enabled: z.boolean().default(false),
       updatedAt: z.string().nullable().default(null),
+      personUid: z.string().optional(),
+      // `.optional()`, NOT `.default(false)`: an older server omits this field,
+      // and materializing it would change the parsed response shape for every
+      // legacy caller. Callers test `unset === true`, so absent reads as
+      // "not unset" and the self-heal path is skipped, which is the pre-existing
+      // behaviour exactly.
+      unset: z.boolean().optional(),
     })
     .strip();
 
+/**
+ * `POST /v1/usage/opt-in` acknowledgement.
+ *
+ * `applied` is absent on older servers (which always wrote unconditionally), so
+ * it stays optional and callers treat absence as "the write landed".
+ */
+const telemetryOptInAckSchema: VaultResponseSchema<{ ok: boolean; applied?: boolean }> = z
+  .object({ ok: z.boolean().default(true), applied: z.boolean().optional() })
+  .strip();
+
 const usageIngestResultSchema: VaultResponseSchema<UsageIngestResult> = z
   .object({
     ok: z.boolean(),
@@ -1353,6 +1389,38 @@ export class VaultClient {
     return this.get("/v1/usage/opt-in", telemetryOptInResponseSchema);
   }
 
+  /**
+   * `POST /v1/usage/opt-in` — record the authenticated caller's consent.
+   *
+   * The installer is the primary writer (it owns the consent prompt). This
+   * client-side setter exists so the sync runner can RE-ASSERT a consent the
+   * user already gave locally but which never reached the server: the
+   * installer's write fires before the person entity exists and 404s on
+   * `no-person-entity`, so the answer survives only in `~/.hq/menubar.json`.
+   * See `./telemetry.ts::collectAndSendTelemetry`, which calls this ONLY when
+   * the server reports `unset` — never over an explicit opt-out.
+   *
+   * `onlyIfUnset` makes the server write conditional on the consent still never
+   * having been recorded. The self-heal MUST pass it: reading `unset` and
+   * replaying the answer are two separate requests, so without the condition
+   * another device could record a real opt-out in between and this replay would
+   * silently overwrite it. A deliberate user choice omits the flag so it always
+   * wins. The response's `applied` reports whether the write landed.
+   */
+  async setTelemetryOptIn(
+    enabled: boolean,
+    opts?: { onlyIfUnset?: boolean },
+  ): Promise<{ applied: boolean }> {
+    const ack = await this.post(
+      "/v1/usage/opt-in",
+      opts?.onlyIfUnset ? { enabled, onlyIfUnset: true } : { enabled },
+      telemetryOptInAckSchema,
+    );
+    // Older servers answer `{ ok: true }` with no `applied`; they also write
+    // unconditionally, so a 2xx there means the write did land.
+    return { applied: ack.applied ?? true };
+  }
+
   /**
    * `POST /v1/usage` — upload a batch of sanitized telemetry events.
    *