@indigoai-us/hq-cloud 6.14.1 → 6.14.3

package/src/telemetry-events.ts

@@ -0,0 +1,205 @@
+import type {
+  TelemetryEventsBatch,
+  TelemetryEventsIngestResult,
+} from "./vault-client.js";
+
+const MAX_EVENTS_PER_BATCH = 50;
+const DEFAULT_TIMEOUT_MS = 1500;
+const MAX_PROPERTIES = 40;
+const MAX_ARRAY_VALUES = 20;
+
+type TelemetryPrimitive = string | number;
+export type TelemetryProperties = Record<
+  string,
+  TelemetryPrimitive | TelemetryPrimitive[] | null | undefined
+>;
+
+export interface TelemetryEvent {
+  eventName: string;
+  source: string;
+  occurredAt?: string;
+  companyUid?: string;
+  agentUid?: string;
+  sessionId?: string;
+  schemaVersion?: 1;
+  properties?: TelemetryProperties;
+}
+
+export interface TelemetryClaims {
+  "custom:entityType"?: unknown;
+  "custom:entityUid"?: unknown;
+}
+
+export interface CloudTelemetryClient {
+  postTelemetryEvents?: (
+    batch: TelemetryEventsBatch,
+    options?: { timeoutMs?: number },
+  ) => Promise<TelemetryEventsIngestResult>;
+}
+
+export interface EmitCloudTelemetryOptions {
+  claims?: TelemetryClaims | null;
+  timeoutMs?: number;
+  log?: (message: string) => void;
+}
+
+const SAFE_KEY = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+const SAFE_LABEL = /^[A-Za-z0-9._:-]{1,128}$/;
+const BLOCKED_STRING_PROPERTY_KEY =
+  /(path|filename|name|email|secret|token|text|message|prompt|body|content|cwd|dir|url|uri|prefix|link)/i;
+
+export function agentUidFromClaims(
+  claims: TelemetryClaims | null | undefined,
+): string | undefined {
+  if (
+    claims?.["custom:entityType"] === "agent" &&
+    typeof claims["custom:entityUid"] === "string" &&
+    claims["custom:entityUid"].startsWith("agt_")
+  ) {
+    return claims["custom:entityUid"];
+  }
+  return undefined;
+}
+
+export async function emitCloudTelemetry(
+  client: CloudTelemetryClient | null | undefined,
+  events: TelemetryEvent | TelemetryEvent[],
+  options: EmitCloudTelemetryOptions = {},
+): Promise<void> {
+  if (!client?.postTelemetryEvents) return;
+
+  const derivedAgentUid = agentUidFromClaims(options.claims);
+  const now = new Date().toISOString();
+  const sanitized = (Array.isArray(events) ? events : [events])
+    .slice(0, MAX_EVENTS_PER_BATCH)
+    .map((event) => sanitizeEvent(event, now, derivedAgentUid))
+    .filter((event): event is TelemetryEventsBatch["events"][number] => event !== null);
+
+  if (sanitized.length === 0) return;
+
+  const timeoutMs = normalizeTimeout(options.timeoutMs);
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timeout = setTimeout(
+      () => reject(new Error(`telemetry events timed out after ${timeoutMs}ms`)),
+      timeoutMs,
+    );
+    timeout.unref?.();
+  });
+
+  const postPromise = client
+    .postTelemetryEvents({ events: sanitized }, { timeoutMs })
+    .catch((err) => {
+      throw err;
+    });
+  postPromise.catch(() => undefined);
+
+  try {
+    await Promise.race([postPromise, timeoutPromise]);
+  } catch (err) {
+    warn(options.log, `postTelemetryEvents failed (${describeError(err)})`);
+  } finally {
+    if (timeout !== undefined) clearTimeout(timeout);
+  }
+}
+
+function sanitizeEvent(
+  event: TelemetryEvent,
+  fallbackOccurredAt: string,
+  derivedAgentUid: string | undefined,
+): TelemetryEventsBatch["events"][number] | null {
+  const eventName = safeLabel(event.eventName);
+  const source = safeLabel(event.source);
+  if (!eventName || !source) return null;
+
+  const occurredAt = safeIso(event.occurredAt) ?? fallbackOccurredAt;
+  const properties = sanitizeProperties(event.properties);
+  const companyUid = safeLabel(event.companyUid);
+  const agentUid = safeLabel(event.agentUid) ?? derivedAgentUid;
+  const sessionId = safeLabel(event.sessionId);
+
+  return {
+    eventName,
+    app: "hq-cloud",
+    source,
+    occurredAt,
+    ...(companyUid ? { companyUid } : {}),
+    ...(agentUid ? { agentUid } : {}),
+    ...(sessionId ? { sessionId } : {}),
+    schemaVersion: 1,
+    ...(properties ? { properties } : {}),
+  };
+}
+
+function sanitizeProperties(
+  properties: TelemetryProperties | undefined,
+): Record<string, unknown> | undefined {
+  if (!properties) return undefined;
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(properties)) {
+    if (Object.keys(out).length >= MAX_PROPERTIES) break;
+    if (!SAFE_KEY.test(key)) continue;
+    const sanitized = sanitizePropertyValue(key, value);
+    if (sanitized !== undefined) out[key] = sanitized;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+function sanitizePropertyValue(
+  key: string,
+  value: unknown,
+): TelemetryPrimitive | TelemetryPrimitive[] | undefined {
+  if (value === null || value === undefined) return undefined;
+  if (Array.isArray(value)) {
+    const values = value
+      .slice(0, MAX_ARRAY_VALUES)
+      .map((item) => sanitizeScalar(key, item))
+      .filter((item): item is TelemetryPrimitive => item !== undefined);
+    return values.length > 0 ? values : undefined;
+  }
+  return sanitizeScalar(key, value);
+}
+
+function sanitizeScalar(
+  key: string,
+  value: unknown,
+): TelemetryPrimitive | undefined {
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : undefined;
+  }
+  if (typeof value !== "string") return undefined;
+  if (BLOCKED_STRING_PROPERTY_KEY.test(key)) return undefined;
+  return safeLabel(value);
+}
+
+function safeLabel(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  if (!SAFE_LABEL.test(trimmed)) return undefined;
+  return trimmed;
+}
+
+function safeIso(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? new Date(parsed).toISOString() : undefined;
+}
+
+function normalizeTimeout(value: number | undefined): number {
+  if (value !== undefined && Number.isFinite(value) && value > 0) {
+    return Math.trunc(value);
+  }
+  return DEFAULT_TIMEOUT_MS;
+}
+
+function warn(log: ((message: string) => void) | undefined, message: string): void {
+  try {
+    (log ?? console.warn)(`[telemetry-events] ${message}`);
+  } catch {
+    /* diagnostics must never affect the caller */
+  }
+}
+
+function describeError(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/src/telemetry.ts

@@ -342,7 +342,7 @@ 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: [] };
+    : { entries: [], bySlug: new Map() };
 
   // 1. Opt-in check (server-authoritative, with local fallback).
   let enabled: boolean;

package/src/vault-client.test.ts

@@ -16,6 +16,7 @@ import {
   type EntityInfo,
   type ExplicitGrant,
   type MembershipSyncConfig,
+  type TelemetryEventsBatch,
 } from "./vault-client.js";
 
 // ---------------------------------------------------------------------------
@@ -275,6 +276,40 @@ describe("API surface", () => {
     });
   });
 
+  it("postTelemetryEvents sends action events without personUid", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, { ok: true, written: 1, skipped: [] }),
+    );
+    const batch: TelemetryEventsBatch = {
+      events: [
+        {
+          eventName: "sync_runner_completed",
+          app: "hq-cloud",
+          source: "sync-runner",
+          occurredAt: "2026-07-07T12:00:00.000Z",
+          companyUid: "cmp_abc",
+          sessionId: "sync_123",
+          schemaVersion: 1,
+          properties: {
+            result: "completed",
+            fileCount: 2,
+          },
+        },
+      ],
+    };
+
+    const result = await client.postTelemetryEvents(batch);
+
+    expect(result).toEqual({ ok: true, written: 1, skipped: [] });
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe("https://vault.test.example.com/v1/telemetry/events");
+    expect((init.method as string).toUpperCase()).toBe("POST");
+    const body = JSON.parse(init.body as string) as Record<string, unknown>;
+    expect(body).toEqual(batch);
+    expect(JSON.stringify(body)).not.toContain("personUid");
+  });
+
   it("updateRole sends correct payload", async () => {
     fetchSpy.mockResolvedValueOnce(
       jsonResponse(200, {
@@ -1067,7 +1102,10 @@ describe("setMembershipSyncConfig (US-004)", () => {
     await expect(
       client.setMembershipSyncConfig("psn_1#cmp_abc", { syncMode: "all" }),
     ).rejects.toThrow(/ETIMEDOUT/);
-    expect(fetchSpy).toHaveBeenCalledTimes(4);
+    const syncConfigCalls = fetchSpy.mock.calls.filter(([url]) =>
+      String(url).includes("/v1/memberships/psn_1%23cmp_abc/sync-config"),
+    );
+    expect(syncConfigCalls).toHaveLength(4);
   });
 });
 

package/src/vault-client.ts

@@ -8,6 +8,7 @@
 
 import type { ClientInfo, VaultServiceConfig } from "./types.js";
 import { buildClientHeaders } from "./client-info.js";
+import { emitCloudTelemetry } from "./telemetry-events.js";
 import { z } from "zod";
 
 // ---------------------------------------------------------------------------
@@ -432,6 +433,34 @@ export interface UsageIngestResult {
   skipped: Array<{ index: number; code: string; error: string }>;
 }
 
+// ---------------------------------------------------------------------------
+// Cloud action telemetry (hq-pro `/v1/telemetry/events`)
+// ---------------------------------------------------------------------------
+
+export interface RawTelemetryEventInput {
+  eventName: string;
+  app: "hq-cloud";
+  source: string;
+  occurredAt: string;
+  companyUid?: string;
+  agentUid?: string;
+  sessionId?: string;
+  schemaVersion?: 1;
+  properties?: Record<string, unknown>;
+}
+
+export interface TelemetryEventsBatch {
+  /**
+   * Action events emitted by sync/CLI surfaces. `personUid` MUST NOT appear in
+   * either the batch or any event — hq-pro resolves the caller server-side from
+   * the Cognito JWT and rejects client-supplied person identifiers.
+   */
+  events: RawTelemetryEventInput[];
+}
+
+/** Same wire shape as `UsageIngestResult`; aliased for call-site clarity. */
+export type TelemetryEventsIngestResult = UsageIngestResult;
+
 // ---------------------------------------------------------------------------
 // Skill-invocation telemetry (hq-pro `/v1/skill-invocations`)
 // ---------------------------------------------------------------------------
@@ -442,11 +471,11 @@ 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, 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.
+   * hasArgs, the optional companyUid edge-attribution field — US-002, and the
+   * optional skillVersion content-hash marker — US-015). 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.
    */
   events: Array<Record<string, unknown>>;
 }
@@ -461,6 +490,11 @@ export type SkillInvocationIngestResult = UsageIngestResult;
 const MAX_RETRIES = 3;
 const BASE_DELAY_MS = 500;
 
+interface VaultRequestOptions {
+  timeoutMs?: number;
+  maxRetries?: number;
+}
+
 function isTransient(status: number): boolean {
   return status === 429 || status >= 500;
 }
@@ -769,6 +803,12 @@ function summarizeZodIssues(issues: readonly z.core.$ZodIssue[]): string {
     .join("; ");
 }
 
+function companyUidFromMembershipId(membershipId: string): string | undefined {
+  const parts = membershipId.split("#");
+  const candidate = parts.length > 1 ? parts[parts.length - 1] : undefined;
+  return candidate?.startsWith("cmp_") ? candidate : undefined;
+}
+
 // ---------------------------------------------------------------------------
 // VaultClient
 // ---------------------------------------------------------------------------
@@ -1019,12 +1059,39 @@ export class VaultClient {
     membershipId: string,
     partial: SetMembershipSyncConfigInput,
   ): Promise<MembershipSyncConfig> {
-    return this.request(
-      "PUT",
-      `/v1/memberships/${encodeURIComponent(membershipId)}/sync-config`,
-      partial,
-      membershipSyncConfigSchema,
-    );
+    const companyUid = companyUidFromMembershipId(membershipId);
+    try {
+      const result = await this.request(
+        "PUT",
+        `/v1/memberships/${encodeURIComponent(membershipId)}/sync-config`,
+        partial,
+        membershipSyncConfigSchema,
+      );
+      void emitCloudTelemetry(this, {
+        eventName: "membership_sync_config_changed",
+        source: "vault-client",
+        ...(companyUid ? { companyUid } : {}),
+        properties: {
+          syncMode: result.syncMode,
+          customPathCount: result.customPaths?.length ?? 0,
+          result: "success",
+          defaultState: result.isDefault ? "default" : "configured",
+        },
+      });
+      return result;
+    } catch (err) {
+      void emitCloudTelemetry(this, {
+        eventName: "membership_sync_config_changed",
+        source: "vault-client",
+        ...(companyUid ? { companyUid } : {}),
+        properties: {
+          syncMode: partial.syncMode,
+          customPathCount: partial.customPaths?.length ?? 0,
+          result: "failure",
+        },
+      });
+      throw err;
+    }
   }
 
   // -- Entity operations ----------------------------------------------------
@@ -1265,6 +1332,25 @@ export class VaultClient {
     return this.post("/v1/skill-invocations", batch, usageIngestResultSchema);
   }
 
+  /**
+   * `POST /v1/telemetry/events` — upload a capped batch of hq-cloud ACTION
+   * events.
+   *
+   * Same trust model as `postUsage`: `personUid` MUST NOT appear in the body;
+   * hq-pro resolves the caller from the JWT and validates any `companyUid`
+   * against the caller's memberships. This endpoint is for server/CLI action
+   * telemetry and is not gated by the personal `/v1/usage` opt-in flag.
+   */
+  async postTelemetryEvents(
+    batch: TelemetryEventsBatch,
+    options: { timeoutMs?: number } = {},
+  ): Promise<TelemetryEventsIngestResult> {
+    return this.post("/v1/telemetry/events", batch, usageIngestResultSchema, {
+      timeoutMs: options.timeoutMs ?? 1500,
+      maxRetries: 0,
+    });
+  }
+
   // -- HTTP primitives with retry -------------------------------------------
 
   private async get<T>(path: string, schema: VaultResponseSchema<T>): Promise<T> {
@@ -1275,8 +1361,9 @@ export class VaultClient {
     path: string,
     body: unknown | undefined,
     schema: VaultResponseSchema<T>,
+    options?: VaultRequestOptions,
   ): Promise<T> {
-    return this.request("POST", path, body, schema);
+    return this.request("POST", path, body, schema, options);
   }
 
   private async request<T>(
@@ -1284,10 +1371,12 @@ export class VaultClient {
     path: string,
     body: unknown,
     schema: VaultResponseSchema<T>,
+    options: VaultRequestOptions = {},
   ): Promise<T> {
     let lastError: Error | undefined;
+    const maxRetries = options.maxRetries ?? MAX_RETRIES;
 
-    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
       if (attempt > 0) {
         const delay = BASE_DELAY_MS * Math.pow(2, attempt - 1);
         await sleep(delay);
@@ -1300,6 +1389,16 @@ export class VaultClient {
       };
 
       const init: RequestInit = { method, headers };
+      const controller =
+        options.timeoutMs !== undefined && options.timeoutMs > 0
+          ? new AbortController()
+          : undefined;
+      let timeout: ReturnType<typeof setTimeout> | undefined;
+      if (controller) {
+        timeout = setTimeout(() => controller.abort(), options.timeoutMs);
+        timeout.unref?.();
+        init.signal = controller.signal;
+      }
 
       if (body !== undefined) {
         headers["Content-Type"] = "application/json";
@@ -1311,8 +1410,10 @@ export class VaultClient {
         res = await fetch(`${this.apiUrl}${path}`, init);
       } catch (err) {
         lastError = err instanceof Error ? err : new Error(String(err));
-        if (attempt < MAX_RETRIES) continue;
+        if (attempt < maxRetries) continue;
         throw lastError;
+      } finally {
+        if (timeout !== undefined) clearTimeout(timeout);
       }
 
       if (res.ok) {

package/src/watcher.test.ts

@@ -331,6 +331,76 @@ describe("US-002: createWatchPathFilter — personal-vault exclusions", () => {
     expect(personal(path.join(ROOT, "workspace"), false)).toBe(false);
   });
 
+  // ── workspace/agency subtree carve-out (personal mode) ──────────────────
+  // The personal push uploads workspace/agency/** (computeAgencySyncPaths), so
+  // the personal watcher must emit those changes event-driven, not leave them
+  // for the 60s poll. Mirrors the continuity-pointer carve-out, for a subtree.
+  it("DOES emit for workspace/agency files in personalMode (synced subtree)", () => {
+    expect(
+      personal(path.join(ROOT, "workspace/agency/indigo/nick/chat.jsonl")),
+    ).toBe(true);
+    expect(
+      personal(path.join(ROOT, "workspace/agency/indigo/nick/status.json")),
+    ).toBe(true);
+    // The agency root itself, as a file event, also emits.
+    expect(personal(path.join(ROOT, "workspace/agency"))).toBe(true);
+  });
+
+  it("allows chokidar to DESCEND to workspace/agency in personalMode (dir probes)", () => {
+    // workspace/ and workspace/agency queried as dirs must return true so the
+    // chokidar backend descends instead of pruning workspace/ at the top.
+    expect(personal(path.join(ROOT, "workspace"), true)).toBe(true);
+    expect(personal(path.join(ROOT, "workspace/agency"), true)).toBe(true);
+    expect(
+      personal(path.join(ROOT, "workspace/agency/indigo"), true),
+    ).toBe(true);
+  });
+
+  it("agency carve-out is exact-segment (does NOT leak to workspace/agencyX)", () => {
+    // Only workspace/agency (and its subtree) is re-included; a sibling whose
+    // name merely starts with 'agency' stays excluded like other workspace litter.
+    expect(personal(path.join(ROOT, "workspace/agencyX/foo.txt"))).toBe(false);
+    expect(personal(path.join(ROOT, "workspace/agency-notes.md"))).toBe(false);
+  });
+
+  it("agency carve-out does not re-include other workspace/ litter", () => {
+    // Regression: the new carve-out must not widen the workspace exclusion for
+    // anything other than agency + the continuity pointer.
+    expect(personal(path.join(ROOT, "workspace/locks/x.lock"))).toBe(false);
+    expect(personal(path.join(ROOT, "workspace/threads/T-old.json"))).toBe(false);
+    expect(personal(path.join(ROOT, "workspace/worktrees/x/a.ts"))).toBe(false);
+  });
+
+  // ── workspace/.session-logs subtree carve-out (personal mode) ────────────
+  // The personal push uploads workspace/.session-logs/** (reindex-captured
+  // Claude Code transcripts, computeSessionLogsSyncPaths), so the personal
+  // watcher must emit those changes event-driven. Mirrors the agency carve-out.
+  it("DOES emit for workspace/.session-logs files in personalMode (synced subtree)", () => {
+    expect(
+      personal(path.join(ROOT, "workspace/.session-logs/session.jsonl")),
+    ).toBe(true);
+    expect(
+      personal(path.join(ROOT, "workspace/.session-logs/tool-results/r.txt")),
+    ).toBe(true);
+    // The subtree root itself, as a file event, also emits.
+    expect(personal(path.join(ROOT, "workspace/.session-logs"))).toBe(true);
+  });
+
+  it("allows chokidar to DESCEND to workspace/.session-logs in personalMode (dir probes)", () => {
+    expect(personal(path.join(ROOT, "workspace"), true)).toBe(true);
+    expect(personal(path.join(ROOT, "workspace/.session-logs"), true)).toBe(true);
+    expect(
+      personal(path.join(ROOT, "workspace/.session-logs/tool-results"), true),
+    ).toBe(true);
+  });
+
+  it("session-logs carve-out is exact-segment (does NOT leak to a similarly-named sibling)", () => {
+    expect(
+      personal(path.join(ROOT, "workspace/.session-logs-old/foo.txt")),
+    ).toBe(false);
+    expect(personal(path.join(ROOT, "workspace/.session-logsX.md"))).toBe(false);
+  });
+
   it("does not apply the carve-out in non-personal mode", () => {
     // In non-personal mode the excluded-top-level layer never runs, so the
     // carve-out is irrelevant; handoff.json passes via the ordinary ignore

package/src/watcher.ts

@@ -14,12 +14,19 @@ import { watch } from "chokidar";
 import { createIgnoreFilter } from "./ignore.js";
 import { isPersonalVaultExcluded } from "./personal-vault-exclusions.js";
 import {
+  AGENCY_SYNC_REL,
   CONTINUITY_POINTER_REL,
+  SESSION_LOGS_SYNC_REL,
   PERSONAL_VAULT_EXCLUDED_TOP_LEVEL,
 } from "./personal-vault.js";
 import type { PushEvent } from "./sync/push-event.js";
 import type { PushTransport } from "./sync/push-transport.js";
 import type { EventDrivenPushFlagProvider } from "./sync/feature-flags.js";
+import {
+  emitCloudTelemetry,
+  type CloudTelemetryClient,
+  type TelemetryClaims,
+} from "./telemetry-events.js";
 
 const DEBOUNCE_MS = 2000;
 
@@ -446,6 +453,36 @@ export function createWatchPathFilter(
       if (rel === CONTINUITY_POINTER_REL && !isDir) return true;
       if (isDir && CONTINUITY_POINTER_REL.startsWith(rel + "/")) return true;
 
+      // Agency-workspace carve-out: `workspace/agency/` (the whole subtree) IS
+      // synced via computeAgencySyncPaths (mirrored on the push side), so it must
+      // re-include BEFORE the top-level `workspace/` rejection below — same
+      // reason as the continuity pointer above, but for an entire subtree rather
+      // than one file. Without this, a `--personal --watch` runner never emits
+      // agency changes and they wait for the 60s poll. Paths at/under agency
+      // emit (handleEvent always probes isDir=false); agency itself and its
+      // ancestor dir (`workspace`) return true for the dir probe so chokidar
+      // descends to reach them instead of pruning `workspace/`.
+      if (rel === AGENCY_SYNC_REL || rel.startsWith(AGENCY_SYNC_REL + "/")) {
+        return true;
+      }
+      if (isDir && AGENCY_SYNC_REL.startsWith(rel + "/")) return true;
+
+      // Session-logs carve-out: `workspace/.session-logs/` (the whole subtree)
+      // IS synced via computeSessionLogsSyncPaths (mirrored on the push side),
+      // so it must re-include BEFORE the top-level `workspace/` rejection below
+      // — identical shape to the agency carve-out just above. Without this, a
+      // `--personal --watch` runner never emits reindex-captured session-log
+      // changes and they wait for the 60s poll. Paths at/under it emit; the
+      // subtree root and its ancestor dir (`workspace`) return true for the dir
+      // probe so chokidar descends to reach them instead of pruning `workspace/`.
+      if (
+        rel === SESSION_LOGS_SYNC_REL ||
+        rel.startsWith(SESSION_LOGS_SYNC_REL + "/")
+      ) {
+        return true;
+      }
+      if (isDir && SESSION_LOGS_SYNC_REL.startsWith(rel + "/")) return true;
+
       // Layer 3: excluded top-level buckets (.git/companies/repos/workspace).
       const topLevel = rel.split("/")[0];
       if (excludedTopLevel.has(topLevel)) return false;
@@ -810,6 +847,9 @@ export interface PushEventEmitterOptions {
    * no log (the daemon stays quiet unless wired with a logger).
    */
   logger?: EmitterLogger;
+  /** Optional hq-pro ACTION telemetry sink. Best-effort; never affects publish. */
+  telemetryClient?: CloudTelemetryClient | null;
+  telemetryClaims?: TelemetryClaims | null;
 }
 
 /**
@@ -834,6 +874,8 @@ export class PushEventEmitter {
   private readonly now: () => Date;
   private readonly onError: (err: Error, ctx: { relativePath?: string }) => void;
   private readonly logger: EmitterLogger | undefined;
+  private readonly telemetryClient: CloudTelemetryClient | null | undefined;
+  private readonly telemetryClaims: TelemetryClaims | null | undefined;
   private internalSeq = 0;
   private readonly nextSeq: () => number;
   private publishTail: Promise<void> = Promise.resolve();
@@ -845,6 +887,8 @@ export class PushEventEmitter {
     this.flagProvider = opts.flagProvider;
     this.now = opts.now ?? (() => new Date());
     this.logger = opts.logger;
+    this.telemetryClient = opts.telemetryClient;
+    this.telemetryClaims = opts.telemetryClaims;
     this.onError =
       opts.onError ??
       ((err, ctx) =>
@@ -945,6 +989,7 @@ export class PushEventEmitter {
         this.onError(err instanceof Error ? err : new Error(String(err)), {
           relativePath,
         });
+        this.emitPublishTelemetry("push_event_failed", "unknown", "capture");
         return;
       }
 
@@ -980,12 +1025,35 @@ export class PushEventEmitter {
 
     try {
       await this.transport.publish(event);
+      this.emitPublishTelemetry("push_event_published", event.kind, "publish");
     } catch (err) {
       // Push failure (network / non-2xx / timeout). The cadence poll is the
       // safety net — log + continue, never throw.
       this.onError(err instanceof Error ? err : new Error(String(err)), {
         relativePath,
       });
+      this.emitPublishTelemetry("push_event_failed", event.kind, "publish");
     }
   }
+
+  private emitPublishTelemetry(
+    eventName: "push_event_published" | "push_event_failed",
+    kind: string,
+    stage: string,
+  ): void {
+    void emitCloudTelemetry(
+      this.telemetryClient,
+      {
+        eventName,
+        source: "watcher",
+        properties: {
+          kind,
+          count: 1,
+          result: eventName === "push_event_published" ? "success" : "failure",
+          stage,
+        },
+      },
+      { claims: this.telemetryClaims },
+    );
+  }
 }