@indigoai-us/hq-cloud 6.11.9 → 6.11.11

package/src/company-resolver.ts

@@ -0,0 +1,147 @@
+/**
+ * cwd → owning-company resolution for telemetry edge attribution
+ * (surface-hq-console-telemetry US-002).
+ *
+ * Both telemetry collectors (`./telemetry.ts`, `./skill-telemetry.ts`) stamp an
+ * optional `companyUid` on each event so the server can attribute usage to the
+ * company that owns the repo the event was produced in. The mapping comes from
+ * `<hqRoot>/companies/manifest.yaml`, whose shape is:
+ *
+ *   companies:
+ *     indigo:
+ *       repos:
+ *         - repos/private/hq-cloud
+ *         - repos/public/hq-core
+ *       cloud_uid: cmp_01KQWRSQTCTES1SEFKXKDZAAK1
+ *     liverecover:
+ *       repos:
+ *         - repos/private/liverecover-site
+ *       # (no cloud_uid — not cloud-backed)
+ *
+ * companyUid source: the value stamped is the manifest's `cloud_uid`. That is a
+ * `cmp_*` entity uid — the SAME value the server membership-keys on
+ * (`membershipKey = '<personUid>#<companyUid>'`, where companyUid is the cmp_*
+ * uid; see hq-pro `vault-service/handlers/usage.ts` + `skill-invocations.ts`).
+ * So no slug→uid round-trip is needed: the manifest already carries the uid the
+ * server expects. A company entry WITHOUT a `cloud_uid` (not cloud-backed, e.g.
+ * `liverecover`/`temple`) contributes no mapping — its repos resolve to no
+ * companyUid and the event is sent unattributed (field omitted).
+ *
+ * The reserved sentinel `unattributed` is NEVER produced here — "no match"
+ * means "return undefined / omit the field", which the server treats as
+ * unattributed/personal.
+ *
+ * Cost: `buildRepoCompanyMap()` parses the manifest ONCE per sync run; the
+ * resulting map is reused for every event via `resolveCompanyForCwd()`. No
+ * per-event manifest reads.
+ *
+ * Privacy: this module only ever returns a `cmp_*` uid (or undefined). It never
+ * adds a raw path to any payload — the collectors add exactly one new field,
+ * `companyUid`.
+ */
+
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+
+import yaml from "js-yaml";
+
+/**
+ * A repo-path → companyUid lookup, built once per run. Keys are ABSOLUTE,
+ * normalized repo roots (`<hqRoot>/repos/private/hq-cloud`); values are the
+ * owning company's `cmp_*` uid. An event `cwd` is attributed to the entry whose
+ * repo root is the longest prefix of (or equal to) the cwd.
+ */
+export interface RepoCompanyMap {
+  /** Absolute, normalized repo root → owning company `cmp_*` uid. */
+  entries: Array<{ repoRoot: string; companyUid: string }>;
+}
+
+interface ManifestCompany {
+  repos?: unknown;
+  cloud_uid?: unknown;
+}
+
+interface ManifestShape {
+  companies?: Record<string, ManifestCompany>;
+}
+
+/** Drop a trailing slash (keeping a bare "/"). Mirrors the scope-path
+ *  normalization in `./skill-telemetry.ts` so prefix matching is consistent. */
+function normalizePath(p: string): string {
+  return p.length > 1 ? p.replace(/\/+$/, "") : p;
+}
+
+/**
+ * Parse `<hqRoot>/companies/manifest.yaml` ONCE and build the repo-path →
+ * companyUid lookup. Best-effort: a missing/unparseable manifest yields an
+ * empty map (every event then resolves to no company → unattributed), so a
+ * telemetry run never fails on a manifest problem.
+ *
+ * Only companies that carry a `cloud_uid` (`cmp_*`) contribute entries — a
+ * company without one is not cloud-backed and its repos stay unattributed.
+ */
+export async function buildRepoCompanyMap(hqRoot: string): Promise<RepoCompanyMap> {
+  const manifestPath = path.join(hqRoot, "companies", "manifest.yaml");
+  let doc: ManifestShape;
+  try {
+    const raw = await fs.readFile(manifestPath, "utf-8");
+    const parsed = yaml.load(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return { entries: [] };
+    }
+    doc = parsed as ManifestShape;
+  } catch {
+    // Missing / unreadable / unparseable — no attribution this run.
+    return { entries: [] };
+  }
+
+  const companies = doc.companies;
+  if (!companies || typeof companies !== "object") return { entries: [] };
+
+  const entries: Array<{ repoRoot: string; companyUid: string }> = [];
+  for (const company of Object.values(companies)) {
+    if (!company || typeof company !== "object") continue;
+    const cloudUid = company.cloud_uid;
+    // Only cloud-backed companies (with a cmp_* uid) attribute events.
+    if (typeof cloudUid !== "string" || !cloudUid.startsWith("cmp_")) continue;
+    const repos = company.repos;
+    if (!Array.isArray(repos)) continue;
+    for (const repo of repos) {
+      if (typeof repo !== "string" || repo.trim().length === 0) continue;
+      // Manifest repo paths are relative to the HQ root (e.g.
+      // `repos/private/hq-cloud`). Resolve to an absolute, normalized root.
+      const repoRoot = normalizePath(path.resolve(hqRoot, repo));
+      entries.push({ repoRoot, companyUid: cloudUid });
+    }
+  }
+
+  // Longest repoRoot first so the first containment match is the most specific
+  // (handles nested repo layouts where one repo path prefixes another).
+  entries.sort((a, b) => b.repoRoot.length - a.repoRoot.length);
+  return { entries };
+}
+
+/**
+ * Resolve an event's `cwd` to the owning company's `cmp_*` uid, or `undefined`
+ * when the cwd is inside no cloud-backed company repo (→ omit `companyUid`;
+ * the server treats absence as unattributed/personal).
+ *
+ * Matching is by path containment: the cwd must equal a repo root or sit
+ * beneath it (`<repoRoot>/...`). A trailing-slash boundary prevents a sibling
+ * that merely shares a string prefix (`<repoRoot>-other`) from matching.
+ * Entries are pre-sorted longest-first, so the first match is the most
+ * specific.
+ */
+export function resolveCompanyForCwd(
+  cwd: string | undefined,
+  map: RepoCompanyMap,
+): string | undefined {
+  if (typeof cwd !== "string" || cwd.length === 0) return undefined;
+  const c = normalizePath(cwd);
+  for (const { repoRoot, companyUid } of map.entries) {
+    if (c === repoRoot || c.startsWith(`${repoRoot}/`)) {
+      return companyUid;
+    }
+  }
+  return undefined;
+}

package/src/personal-vault.ts

@@ -94,6 +94,15 @@ export interface PersonalVaultOptions {
  * hqRoot returns []; callers treat that as "no personal content to push"
  * rather than a hard error.
  */
+/**
+ * S3 key (hq-root-relative, forward-slash) of the companies manifest — the
+ * routing source-of-truth — carved into the personal vault even though
+ * `companies/` is otherwise excluded. Exported so the PULL plan applies the
+ * SAME exemption: skipping it on the pull leaves it unjournaled, which re-fires
+ * a transient push-side conflict every sync (no journal baseline).
+ */
+export const PERSONAL_VAULT_MANIFEST_KEY = "companies/manifest.yaml";
+
 export function computePersonalVaultPaths(
   hqRoot: string,
   opts: PersonalVaultOptions = {},
@@ -114,7 +123,7 @@ export function computePersonalVaultPaths(
   // because the parent `companies/` is in PERSONAL_VAULT_EXCLUDED_TOP_LEVEL
   // (we never enumerate the whole companies tree wholesale).
   const manifest: string[] = [];
-  const manifestPath = path.join(hqRoot, "companies", "manifest.yaml");
+  const manifestPath = path.join(hqRoot, PERSONAL_VAULT_MANIFEST_KEY);
   try {
     if (fs.statSync(manifestPath).isFile()) {
       manifest.push(manifestPath);

package/src/skill-telemetry.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi } from "vitest";
 import { promises as fs } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -923,3 +923,128 @@ describe("collectAndSendSkillTelemetry — hqRoot scoping", () => {
     await fs.rm(tmp, { recursive: true, force: true });
   });
 });
+
+// ── companyUid edge attribution (US-002) ────────────────────────────────────────
+
+describe("collectAndSendSkillTelemetry — companyUid attribution", () => {
+  const COMPANY_UID = "cmp_01INDIGOSKILL";
+
+  function stubClient(captured: SkillInvocationBatch[]) {
+    return {
+      async getTelemetryOptIn() {
+        return { enabled: true, updatedAt: null };
+      },
+      async postSkillInvocations(batch: SkillInvocationBatch) {
+        captured.push(batch);
+        return { ok: true, written: batch.events.length, skipped: [] };
+      },
+    };
+  }
+
+  function row(obj: Record<string, unknown>): string {
+    return JSON.stringify(obj);
+  }
+
+  /** Write a manifest mapping `repos/private/hq-cloud` → COMPANY_UID under hqRoot. */
+  async function writeManifest(hqRoot: string): Promise<void> {
+    await fs.mkdir(path.join(hqRoot, "companies"), { recursive: true });
+    await fs.writeFile(
+      path.join(hqRoot, "companies", "manifest.yaml"),
+      `companies:\n  indigo:\n    repos:\n      - repos/private/hq-cloud\n    cloud_uid: ${COMPANY_UID}\n`,
+      "utf-8",
+    );
+  }
+
+  it("stamps companyUid when cwd is inside a company repo, omits it otherwise", async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "skill-tel-co-"));
+    const hqRoot = tmp; // real dir so the manifest's repo path resolves under it
+    await writeManifest(hqRoot);
+    const projects = path.join(tmp, "projects");
+    const dir = path.join(projects, "-p");
+    await fs.mkdir(dir, { recursive: true });
+
+    const inRepo = path.join(hqRoot, "repos/private/hq-cloud");
+    const atRoot = hqRoot; // inside scope, but not inside any mapped repo
+    await fs.writeFile(
+      path.join(dir, "s.jsonl"),
+      [
+        // cwd inside the company repo → attributed.
+        row({ type: "user", sessionId: "s1", timestamp: "2026-06-10T10:00:00Z", cwd: inRepo, uuid: "u1", message: { role: "user", content: "<command-name>/deploy</command-name>" } }),
+        // cwd at hqRoot (passes scope) but maps to no repo → unattributed.
+        row({ type: "assistant", sessionId: "s1", timestamp: "2026-06-10T10:01:00Z", cwd: atRoot, message: { role: "assistant", content: [{ type: "tool_use", id: "t1", name: "Skill", input: { skill: "indigo:hello-world" } }] } }),
+      ].join("\n") + "\n",
+      "utf-8",
+    );
+
+    const captured: SkillInvocationBatch[] = [];
+    const result = await collectAndSendSkillTelemetry({
+      client: stubClient(captured),
+      machineId: "m",
+      installerVersion: "t",
+      hqRoot,
+      claudeProjectsRoot: projects,
+      codexSessionsRoot: path.join(tmp, "codex"),
+      cursorPath: path.join(tmp, "cursor.json"),
+    });
+
+    expect(result.eventsSent).toBe(2);
+    const events = captured.flatMap((b) => b.events);
+    const bySkill = new Map(events.map((e) => [e.skill, e]));
+    expect(bySkill.get("deploy")!.companyUid).toBe(COMPANY_UID);
+    expect("companyUid" in bySkill.get("indigo:hello-world")!).toBe(false);
+    // Never the reserved sentinel.
+    for (const e of events) expect(e.companyUid).not.toBe("unattributed");
+
+    await fs.rm(tmp, { recursive: true, force: true });
+  });
+
+  it("parses the manifest once per run (cache), not per event", async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "skill-tel-cache-"));
+    const hqRoot = tmp;
+    await writeManifest(hqRoot);
+    const projects = path.join(tmp, "projects");
+    const dir = path.join(projects, "-p");
+    await fs.mkdir(dir, { recursive: true });
+    const inRepo = path.join(hqRoot, "repos/private/hq-cloud");
+    await fs.writeFile(
+      path.join(dir, "s.jsonl"),
+      Array.from({ length: 4 }, (_, i) =>
+        row({ type: "user", sessionId: "s1", timestamp: `2026-06-10T10:0${i}:00Z`, cwd: inRepo, uuid: `u${i}`, message: { role: "user", content: "<command-name>/deploy</command-name>" } }),
+      ).join("\n") + "\n",
+      "utf-8",
+    );
+
+    const manifestPath = path.join(hqRoot, "companies", "manifest.yaml");
+    const realReadFile = fs.readFile;
+    let manifestReads = 0;
+    const spy = vi
+      .spyOn(fs, "readFile")
+      .mockImplementation((async (p: Parameters<typeof realReadFile>[0], ...rest: unknown[]) => {
+        if (typeof p === "string" && p === manifestPath) manifestReads++;
+        // @ts-expect-error pass-through to the real implementation
+        return realReadFile(p, ...rest);
+      }) as typeof realReadFile);
+
+    const captured: SkillInvocationBatch[] = [];
+    try {
+      await collectAndSendSkillTelemetry({
+        client: stubClient(captured),
+        machineId: "m",
+        installerVersion: "t",
+        hqRoot,
+        claudeProjectsRoot: projects,
+        codexSessionsRoot: path.join(tmp, "codex"),
+        cursorPath: path.join(tmp, "cursor.json"),
+      });
+    } finally {
+      spy.mockRestore();
+    }
+
+    expect(manifestReads).toBe(1);
+    const events = captured.flatMap((b) => b.events);
+    expect(events).toHaveLength(4);
+    for (const e of events) expect(e.companyUid).toBe(COMPANY_UID);
+
+    await fs.rm(tmp, { recursive: true, force: true });
+  });
+});

package/src/skill-telemetry.ts

@@ -59,6 +59,11 @@ import { promises as fs } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
+import {
+  buildRepoCompanyMap,
+  resolveCompanyForCwd,
+  type RepoCompanyMap,
+} from "./company-resolver.js";
 import type {
   SkillInvocationBatch,
   SkillInvocationIngestResult,
@@ -533,8 +538,15 @@ export function extractCodexSkillToolEvents(
   ];
 }
 
-/** Shape the event for the wire. Drops raw args unless explicitly enabled. */
-function toWireRow(ev: SkillEvent): Record<string, unknown> {
+/** Shape the event for the wire. Drops raw args unless explicitly enabled.
+ *
+ *  `companyUid` (US-002): the caller resolves the event's `cwd` → owning company
+ *  (`resolveCompanyForCwd`) and passes that `cmp_*` uid here. It is on the
+ *  server's KEEP allowlist (`apps/hq-pro/src/vault-service/handlers/
+ *  skill-invocations.ts`). When undefined (cwd maps to no company repo) the
+ *  field is OMITTED — the server treats absence as unattributed/personal. The
+ *  reserved value `unattributed` is never produced. */
+function toWireRow(ev: SkillEvent, companyUid?: string): Record<string, unknown> {
   const row: Record<string, unknown> = {
     skill: ev.skill,
     source: ev.source,
@@ -544,6 +556,7 @@ function toWireRow(ev: SkillEvent): Record<string, unknown> {
   if (ev.timestamp !== undefined) row.timestamp = ev.timestamp;
   if (ev.uuid !== undefined) row.uuid = ev.uuid;
   if (ev.cwd !== undefined) row.cwd = ev.cwd;
+  if (companyUid !== undefined) row.companyUid = companyUid;
   // INCLUDE_ARGS_PREVIEW is intentionally a compile-time constant `false`;
   // the guarded branch documents the (currently disabled) egress path.
   if (INCLUDE_ARGS_PREVIEW) {
@@ -643,6 +656,13 @@ export async function collectAndSendSkillTelemetry(
   const normalizePath = (p: string): string => (p.length > 1 ? p.replace(/\/+$/, "") : p);
   const scopeCwd = opts.hqRoot !== undefined ? normalizePath(opts.hqRoot) : undefined;
 
+  // Company attribution (US-002): parse the manifest ONCE per run and reuse the
+  // repo-path→companyUid map for every event below. No per-event manifest read.
+  // When `hqRoot` is omitted the map is empty → every event stays unattributed.
+  const repoCompanyMap: RepoCompanyMap = opts.hqRoot
+    ? await buildRepoCompanyMap(opts.hqRoot)
+    : { entries: [] };
+
   // 1. Opt-in check — reuse the same gate as token telemetry.
   let enabled: boolean;
   let optInSource: CollectSkillTelemetryResult["optInSource"];
@@ -788,7 +808,10 @@ export async function collectAndSendSkillTelemetry(
             continue;
           }
         }
-        sourced.push({ row: toWireRow(ev), filePath, endOffset });
+        // Resolve cwd → owning company (cmp_* uid) from the per-run map.
+        // Unresolved → undefined → companyUid omitted (unattributed/personal).
+        const companyUid = resolveCompanyForCwd(ev.cwd, repoCompanyMap);
+        sourced.push({ row: toWireRow(ev, companyUid), filePath, endOffset });
         fileScans[filePath].eventCount++;
       }
     }

package/src/sync/pull-scope.ts

@@ -35,7 +35,7 @@ import type {
  */
 export interface PullScopeClient {
   listMyMemberships(): Promise<
-    Array<{ companyUid: string; membershipKey: string }>
+    Array<{ companyUid: string; membershipKey: string; role?: string }>
   >;
   getMembershipSyncConfig?: (
     membershipId: string,
@@ -82,6 +82,31 @@ export async function resolvePullScope(
     const memberships = await client.listMyMemberships();
     const m = memberships.find((x) => x.companyUid === companyUid);
     if (!m) return { syncMode: "all" };
+    // OWNER role-bypass (feedback_67bdb8a4 / feedback_a46c3b37). An owner's
+    // effective vault access is the WHOLE company by role — the data plane
+    // resolves owner to `admin` on every key (`resolveEffectivePermission`'s
+    // role bypass; presign's `viewOthersFiles` is unconditional for owners).
+    // But the scope resolution below derives `shared` scope from
+    // `listMyExplicitGrants`, and that endpoint DELIBERATELY EXCLUDES the
+    // owner/admin role bypass — it answers "what is explicitly shared with
+    // me", not "what can I touch by role" (see hq-pro files-grants handler).
+    // An owner who owns by role (not by explicit grant) therefore resolves to
+    // an empty/sparse prefixSet, so the push uploads NOTHING (every path is
+    // filtered out by `wrapFilterWithScope`) and any in-role write — including
+    // a brand-new top-level project prefix the owner just created — is rejected
+    // by the server as `403 SCOPE_EXCEEDS_PARENT`. An owner has no meaningful
+    // "shared subset": they own everything, so their effective sync scope IS
+    // the full vault. Resolve them to `all` directly — restoring the pre-
+    // pull-scope-refactor behavior (owners always journaled the whole company).
+    // This is checked BEFORE the sync-config fetch so it holds even if a stray
+    // `shared` row exists for the owner. A `custom` choice would also be
+    // overridden here, which is intentional: an owner cannot be scoped below
+    // their role on the sync path without the server rejecting their own
+    // writes. Non-owner roles fall through to the grant-based resolution
+    // below — a member/guest's explicit grants ARE their full footprint, and a
+    // (conditionally bypassed) admin stays grant-scoped so a company that set
+    // `admin.viewOthersFiles=false` keeps its admins narrowed.
+    if (m.role === "owner") return { syncMode: "all" };
     // Agent memberships (`agt_…#cmp_…`) belong to an agent identity that owns NO
     // person entity. hq-pro's per-membership sync-config endpoint sits behind an
     // up-front person-gate, so an agent caller is rejected with

package/src/telemetry.test.ts

@@ -8,8 +8,9 @@
  * boundary is `TelemetryClientSurface`, not the HTTP layer.
  */
 
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 import * as fs from "fs";
+import { promises as fsp } from "fs";
 import * as os from "os";
 import * as path from "path";
 import {
@@ -186,11 +187,20 @@ describe("sanitizeRow", () => {
       "sessionId", "timestamp", "uuid", "cwd", "gitBranch", "userType",
       "model", "inputTokens", "outputTokens",
       "cacheCreationInputTokens", "cacheReadInputTokens",
+      "companyUid",
     ]);
     for (const key of Object.keys(out)) {
       expect(allowed.has(key), `field "${key}" must be in server allowlist`).toBe(true);
     }
   });
+
+  it("(US-002) stamps companyUid when provided, omits it when not", () => {
+    const withUid = sanitizeRow(JSON.parse(USER_ROW), "cmp_01INDIGO")!;
+    expect(withUid.companyUid).toBe("cmp_01INDIGO");
+
+    const withoutUid = sanitizeRow(JSON.parse(USER_ROW))!;
+    expect("companyUid" in withoutUid).toBe(false);
+  });
 });
 
 // ── collectAndSendTelemetry ───────────────────────────────────────────────────
@@ -392,3 +402,110 @@ describe("collectAndSendTelemetry", () => {
     expect(client.posts).toHaveLength(1); // no second POST
   });
 });
+
+// ── companyUid edge attribution (US-002) ────────────────────────────────────────
+
+describe("collectAndSendTelemetry — companyUid attribution", () => {
+  const COMPANY_UID = "cmp_01INDIGOTEST";
+  let env: TestEnv;
+  let hqRoot: string;
+
+  // The manifest lives at <hqRoot>/companies/manifest.yaml; the repo it maps is
+  // a real subdir of hqRoot so the resolver's absolute-path math lines up.
+  function writeManifest(): void {
+    fs.mkdirSync(path.join(hqRoot, "companies"), { recursive: true });
+    fs.writeFileSync(
+      path.join(hqRoot, "companies", "manifest.yaml"),
+      `companies:\n  indigo:\n    repos:\n      - repos/private/hq-cloud\n    cloud_uid: ${COMPANY_UID}\n`,
+    );
+  }
+
+  function rowWithCwd(uuid: string, cwd: string): string {
+    return JSON.stringify({
+      type: "user",
+      timestamp: "2026-06-10T10:00:00Z",
+      sessionId: "s1",
+      uuid,
+      userType: "human",
+      cwd,
+      message: { role: "user", content: [{ type: "text", text: "hi" }] },
+    });
+  }
+
+  beforeEach(() => {
+    env = setupEnv();
+    // Use the same tmp root as hqRoot so the repo path resolves under it.
+    hqRoot = env.root;
+    writeManifest();
+  });
+  afterEach(() => { teardownEnv(env); });
+
+  it("stamps companyUid on events whose cwd is inside a company repo", async () => {
+    const client = makeClient();
+    const inRepo = path.join(hqRoot, "repos/private/hq-cloud/src");
+    writeJsonl(env, "proj", "s.jsonl", [rowWithCwd("u1", inRepo)]);
+
+    await collectAndSendTelemetry({ ...makeOpts(env, client), hqRoot });
+
+    expect(client.posts).toHaveLength(1);
+    expect(client.posts[0].events[0].companyUid).toBe(COMPANY_UID);
+  });
+
+  it("omits companyUid when the cwd maps to no company repo", async () => {
+    const client = makeClient();
+    writeJsonl(env, "proj", "s.jsonl", [rowWithCwd("u1", "/Users/x/some-other-repo")]);
+
+    await collectAndSendTelemetry({ ...makeOpts(env, client), hqRoot });
+
+    expect(client.posts).toHaveLength(1);
+    expect("companyUid" in client.posts[0].events[0]).toBe(false);
+  });
+
+  it("never sends the reserved 'unattributed' value", async () => {
+    const client = makeClient();
+    writeJsonl(env, "proj", "s.jsonl", [
+      rowWithCwd("u1", path.join(hqRoot, "repos/private/hq-cloud")),
+      rowWithCwd("u2", "/elsewhere"),
+    ]);
+
+    await collectAndSendTelemetry({ ...makeOpts(env, client), hqRoot });
+
+    for (const ev of client.posts.flatMap((p) => p.events)) {
+      expect(ev.companyUid).not.toBe("unattributed");
+    }
+  });
+
+  it("parses the manifest once per run (cache), not per event", async () => {
+    const client = makeClient();
+    const inRepo = path.join(hqRoot, "repos/private/hq-cloud");
+    // 5 events in one run; assert the manifest file is read exactly once.
+    writeJsonl(
+      env,
+      "proj",
+      "s.jsonl",
+      Array.from({ length: 5 }, (_, i) => rowWithCwd(`u${i}`, inRepo)),
+    );
+
+    const manifestPath = path.join(hqRoot, "companies", "manifest.yaml");
+    const realReadFile = fsp.readFile;
+    let manifestReads = 0;
+    const spy = vi
+      .spyOn(fsp, "readFile")
+      .mockImplementation((async (p: Parameters<typeof realReadFile>[0], ...rest: unknown[]) => {
+        if (typeof p === "string" && p === manifestPath) manifestReads++;
+        // @ts-expect-error pass-through to the real implementation
+        return realReadFile(p, ...rest);
+      }) as typeof realReadFile);
+
+    try {
+      await collectAndSendTelemetry({ ...makeOpts(env, client), hqRoot });
+    } finally {
+      spy.mockRestore();
+    }
+
+    expect(manifestReads).toBe(1); // one parse for all 5 events
+    const events = client.posts.flatMap((p) => p.events);
+    expect(events).toHaveLength(5);
+    for (const ev of events) expect(ev.companyUid).toBe(COMPANY_UID);
+  });
+});

package/src/telemetry.ts

@@ -27,6 +27,11 @@ import { promises as fs } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
+import {
+  buildRepoCompanyMap,
+  resolveCompanyForCwd,
+  type RepoCompanyMap,
+} from "./company-resolver.js";
 import type {
   TelemetryOptInResponse,
   UsageBatch,
@@ -51,6 +56,15 @@ export interface CollectTelemetryOptions {
   machineId: string;
   /** Version of the wrapping caller (menubar app, CLI, etc.). Reaches CloudWatch metrics as the `installerVersion` dimension. */
   installerVersion: string;
+  /**
+   * HQ root, used to resolve each event's `cwd` → owning repo → owning company
+   * via `<hqRoot>/companies/manifest.yaml` and stamp `companyUid` on the event
+   * (surface-hq-console-telemetry US-002). The manifest is parsed ONCE per run
+   * (see `buildRepoCompanyMap`); the resulting map is reused for every event.
+   * When omitted (or when no repo matches), `companyUid` is left UNSET and the
+   * server treats the event as unattributed/personal.
+   */
+  hqRoot?: string;
   /** Override `~/.claude/projects` for tests. */
   claudeProjectsRoot?: string;
   /** Override `~/.hq/telemetry-cursor.json` for tests. */
@@ -148,12 +162,23 @@ const KEEP_TOP_LEVEL = [
  *      camelCase top-level fields. The original `message` object — which
  *      carries prompt/response text, thinking, and tool data — is dropped.
  *
+ * `companyUid` (US-002): when the caller has resolved the row's `cwd` to an
+ * owning company (`resolveCompanyForCwd`), it passes that `cmp_*` uid here and
+ * it is stamped on the wire row. It is on the server's KEEP allowlist
+ * (`apps/hq-pro/src/vault-service/handlers/usage.ts`). When `companyUid` is
+ * undefined (cwd maps to no company repo) the field is OMITTED — the server
+ * treats absence as unattributed/personal. The reserved value `unattributed`
+ * is never produced (it can only come from a resolved manifest `cmp_*` uid).
+ *
  * Returns `null` when the input isn't an object. Empty results (e.g. a row
  * with no recognised fields) are still returned as `{}` and emitted; the
  * server accepts empty rows and they're useful as a "Claude Code was run at
  * this time" heartbeat.
  */
-export function sanitizeRow(row: unknown): Record<string, unknown> | null {
+export function sanitizeRow(
+  row: unknown,
+  companyUid?: string,
+): Record<string, unknown> | null {
   if (!row || typeof row !== "object" || Array.isArray(row)) return null;
   const obj = row as Record<string, unknown>;
   const out: Record<string, unknown> = {};
@@ -164,6 +189,12 @@ export function sanitizeRow(row: unknown): Record<string, unknown> | null {
     }
   }
 
+  // Stamp the resolved company attribution. Omit when unresolved so the server
+  // reads it as unattributed/personal. Never the reserved `unattributed`.
+  if (companyUid !== undefined) {
+    out.companyUid = companyUid;
+  }
+
   const message = obj.message;
   if (message && typeof message === "object" && !Array.isArray(message)) {
     const m = message as Record<string, unknown>;
@@ -261,6 +292,13 @@ export async function collectAndSendTelemetry(
   const menubarPath = opts.menubarPath ?? path.join(home, ".hq", "menubar.json");
   const log = opts.log ?? (() => {});
 
+  // Company attribution (US-002): parse the manifest ONCE per run and reuse the
+  // repo-path→companyUid map for every event below. No per-event manifest read.
+  // When `hqRoot` is omitted the map is empty → every event stays unattributed.
+  const repoCompanyMap: RepoCompanyMap = opts.hqRoot
+    ? await buildRepoCompanyMap(opts.hqRoot)
+    : { entries: [] };
+
   // 1. Opt-in check (server-authoritative, with local fallback).
   let enabled: boolean;
   let optInSource: CollectTelemetryResult["optInSource"];
@@ -390,7 +428,17 @@ export async function collectAndSendTelemetry(
       } catch {
         continue;
       }
-      const sanitized = sanitizeRow(parsed);
+      // Resolve this row's cwd → owning company (cmp_* uid) before sanitizing,
+      // using the per-run map. Unresolved → undefined → companyUid omitted.
+      const rowCwd =
+        parsed && typeof parsed === "object" && !Array.isArray(parsed)
+          ? (parsed as Record<string, unknown>).cwd
+          : undefined;
+      const companyUid = resolveCompanyForCwd(
+        typeof rowCwd === "string" ? rowCwd : undefined,
+        repoCompanyMap,
+      );
+      const sanitized = sanitizeRow(parsed, companyUid);
       if (!sanitized) continue;
 
       // Cost of appending this row to the current batch: the row's JSON

package/src/vault-client.ts

@@ -393,7 +393,8 @@ export interface UsageBatch {
    * Sanitized event rows. Each row is a plain object containing only the
    * fields in the server's KEEP allowlist (sessionId, timestamp, uuid, cwd,
    * gitBranch, userType, model, inputTokens, outputTokens,
-   * cacheCreationInputTokens, cacheReadInputTokens). Any extra field is
+   * cacheCreationInputTokens, cacheReadInputTokens, and the optional
+   * companyUid edge-attribution field — US-002). Any extra field is
    * rejected by hq-pro with `unexpected-event-field`, so the sanitizer in
    * `./telemetry.ts` is the only thing allowed to produce these.
    */
@@ -416,7 +417,8 @@ export interface SkillInvocationBatch {
   /**
    * Skill-invocation event rows. Each row contains only the fields in the
    * server's KEEP allowlist (skill, source, sessionId, timestamp, uuid, cwd,
-   * hasArgs). Raw argument text is never included — see the privacy note in
+   * hasArgs, and the optional companyUid edge-attribution field — US-002).
+   * Raw argument text is never included — see the privacy note in
    * `./skill-telemetry.ts`. Any extra field is rejected by hq-pro with
    * `unexpected-event-field`, so the extractor in `./skill-telemetry.ts` is the
    * only thing allowed to produce these.