@indigoai-us/hq-cloud 6.14.23 → 6.14.25

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.
    *

package/src/watcher.test.ts

@@ -796,3 +796,36 @@ describe("PushEventEmitter — directory and delete tombstone handling", () => {
     ]);
   });
 });
+
+describe("TreeWatcher wire-key codec boundary (US-002)", () => {
+  it("emits the canonical vault key for an encoded win32 farm name (verbatim local name on POSIX)", () => {
+    const hqRoot = path.join(os.tmpdir(), "hq-watch-codec-test-root");
+    const clock = new FakeClock();
+    const watcher = new TreeWatcher({
+      hqRoot,
+      clock,
+      debounceMs: 100,
+      pathFilter: () => true,
+    });
+    const rels: string[] = [];
+    watcher.onChange((_first, batch) => {
+      if (batch) rels.push(...batch.paths.values());
+    });
+
+    watcher.handleEvent(
+      path.join(hqRoot, ".claude", "skills", "indigo%3Acall-prep-brief"),
+    );
+    clock.advance(200);
+
+    // The batch rel is a WIRE identifier (PushEvent.relativePath / targeted
+    // push route). On win32 the encoded local farm name must decode back to
+    // the canonical key or event-driven push re-mints the junk key family;
+    // on POSIX the local name IS the key verbatim (codec is identity there).
+    const expectedRel =
+      process.platform === "win32"
+        ? ".claude/skills/indigo:call-prep-brief"
+        : ".claude/skills/indigo%3Acall-prep-brief";
+    expect(rels).toEqual([expectedRel]);
+    watcher.dispose();
+  });
+});

package/src/watcher.ts

@@ -12,6 +12,7 @@ import { readFile, stat } from "node:fs/promises";
 import * as path from "path";
 import { watch } from "chokidar";
 import { createIgnoreFilter } from "./ignore.js";
+import { vaultKeyForLocalPath } from "./local-path-codec.js";
 import { isPersonalVaultExcluded } from "./personal-vault-exclusions.js";
 import {
   AGENCY_SYNC_REL,
@@ -734,7 +735,15 @@ export class TreeWatcher {
     // authoritative emit gate; the chokidar backend's `ignored` pre-filters
     // but a slipped-through (or synthetic test) path is re-checked here too.
     if (!this.shouldEmit(abs, isDir)) return;
-    const rel = path.relative(this.hqRoot, abs).split(path.sep).join("/");
+    // Codec boundary: the batch's relative path is a WIRE identifier — it
+    // becomes `PushEvent.relativePath` and the targeted-push route key — so
+    // a win32 local farm name (`indigo%3Ax`) must decode back to its
+    // canonical vault-key spelling (`indigo:x`) here. Emitting the encoded
+    // local name verbatim would mint a fresh junk key family on the wire
+    // (the mixed-version amplifier). The emit filter above still sees the
+    // raw local path: its exclusion patterns live in local-name space and
+    // none of them contain codec-reserved characters.
+    const rel = vaultKeyForLocalPath(this.hqRoot, abs);
     if (!this.pending.has(abs)) {
       const entryBytes = estimatePendingEntryBytes(abs, rel);
       if (