@indigoai-us/hq-cloud 6.11.14 → 6.11.15

package/src/bin/sync-runner.ts

@@ -107,6 +107,7 @@ import { collectAndSendSkillTelemetry } from "../skill-telemetry.js";
 import { reindexAfterSync } from "../qmd-reindex.js";
 import { pruneConflictIndex } from "../lib/conflict-index.js";
 import { getOrCreateMachineId } from "../lib/machine-id.js";
+import { describeError } from "../lib/describe-error.js";
 import type { Clock, TreeChangeBatch } from "../watcher.js";
 import type { PushReceiver, SyncEngineFn } from "../sync/push-receiver.js";
 import {
@@ -404,6 +405,53 @@ export interface VaultClientSurface {
   listMyExplicitGrants?: (companyUid: string) => Promise<ExplicitGrant[]>;
 }
 
+interface RunnerDiagnostic {
+  component: string;
+  event: string;
+  message: string;
+  err?: unknown;
+  context?: Record<string, unknown>;
+}
+
+type RunnerDiagnosticReporter = (diagnostic: RunnerDiagnostic) => void;
+
+function errorDetails(err: unknown): Record<string, unknown> {
+  const details: Record<string, unknown> = { message: describeError(err) };
+  if (err instanceof Error) {
+    if (err.name) details.name = err.name;
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code) details.code = code;
+  }
+  return details;
+}
+
+function createRunnerDiagnosticReporter(
+  stderr: { write: (chunk: string) => boolean | void },
+): RunnerDiagnosticReporter {
+  return (diagnostic) => {
+    try {
+      const payload: Record<string, unknown> = {
+        type: "error",
+        diagnostic: true,
+        component: diagnostic.component,
+        event: diagnostic.event,
+        path: `(${diagnostic.component})`,
+        message:
+          diagnostic.err === undefined
+            ? diagnostic.message
+            : `${diagnostic.message}: ${describeError(diagnostic.err)}`,
+        ...(diagnostic.context ?? {}),
+      };
+      if (diagnostic.err !== undefined) {
+        payload.err = errorDetails(diagnostic.err);
+      }
+      stderr.write(`${JSON.stringify(payload)}\n`);
+    } catch {
+      /* diagnostics must never affect runner control flow */
+    }
+  };
+}
+
 // `resolvePullScope`, `readPinnedPrefixes`, and the `PullScope` type now live
 // in `../sync/pull-scope.ts` so the menubar runner and `hq sync pull|now`
 // (hq-cli) share ONE scope resolver — the drift between them was the root
@@ -769,6 +817,7 @@ export async function defaultCollectTelemetry(
   client: VaultClientSurface,
   clientIsStub: boolean,
   hqRoot: string,
+  reportDiagnostic: RunnerDiagnosticReporter = () => undefined,
 ): Promise<void> {
   if (clientIsStub) return;
 
@@ -797,7 +846,14 @@ export async function defaultCollectTelemetry(
   try {
     const persons = await client.entity.listByType("person");
     if (pickCanonicalPersonEntity(persons) === null) return;
-  } catch {
+  } catch (err) {
+    reportDiagnostic({
+      component: "telemetry",
+      event: "runner.telemetry.person_probe_failed",
+      message: "telemetry person probe failed; continuing with telemetry",
+      err,
+      context: { hqRoot },
+    });
     // Probe failed — preserve prior behavior and let telemetry run.
   }
 
@@ -820,7 +876,14 @@ export async function defaultCollectTelemetry(
   try {
     machineId = getOrCreateMachineId(hqRoot);
     installerVersion = process.env.HQ_INSTALLER_VERSION ?? "hq-cloud";
-  } catch {
+  } catch (err) {
+    reportDiagnostic({
+      component: "telemetry",
+      event: "runner.telemetry.identity_failed",
+      message: "telemetry identity resolution failed; skipping telemetry",
+      err,
+      context: { hqRoot },
+    });
     return;
   }
 
@@ -836,8 +899,22 @@ export async function defaultCollectTelemetry(
       // manifest.yaml and stamp companyUid (US-002). Unmatched cwds stay
       // unattributed (field omitted).
       hqRoot,
+      log: (message) =>
+        reportDiagnostic({
+          component: "telemetry",
+          event: "runner.telemetry.usage_nonfatal",
+          message,
+          context: { hqRoot },
+        }),
+    });
+  } catch (err) {
+    reportDiagnostic({
+      component: "telemetry",
+      event: "runner.telemetry.usage_failed",
+      message: "usage telemetry collector threw",
+      err,
+      context: { hqRoot },
     });
-  } catch {
     // Fire-and-forget; nothing escapes the boundary.
   }
 
@@ -851,8 +928,22 @@ export async function defaultCollectTelemetry(
       // Scope skill capture to the HQ project — only invocations whose cwd is
       // the HQ root are emitted; skill usage in unrelated repos is excluded.
       hqRoot,
+      log: (message) =>
+        reportDiagnostic({
+          component: "telemetry",
+          event: "runner.telemetry.skill_nonfatal",
+          message,
+          context: { hqRoot },
+        }),
+    });
+  } catch (err) {
+    reportDiagnostic({
+      component: "telemetry",
+      event: "runner.telemetry.skill_failed",
+      message: "skill telemetry collector threw",
+      err,
+      context: { hqRoot },
     });
-  } catch {
     // Fire-and-forget; nothing escapes the boundary.
   }
 }
@@ -867,6 +958,7 @@ export async function runRunner(
 ): Promise<number> {
   const stdout = deps.stdout ?? process.stdout;
   const stderr = deps.stderr ?? process.stderr;
+  const reportDiagnostic = createRunnerDiagnosticReporter(stderr);
 
   // ---- emit ---------------------------------------------------------------
   // Error-class events go to stderr; everything else to stdout.
@@ -1068,7 +1160,16 @@ export async function runRunner(
         client,
         deps.createVaultClient !== undefined,
         parsed.hqRoot,
+        reportDiagnostic,
       ),
+    onError: (err) =>
+      reportDiagnostic({
+        component: "telemetry",
+        event: "runner.telemetry.collector_failed",
+        message: "telemetry collector failed",
+        err,
+        context: { hqRoot: parsed.hqRoot },
+      }),
   });
 
   emit({
@@ -1095,8 +1196,24 @@ export async function runRunner(
     process.env.HQ_QMD_REINDEX_ON_SYNC !== "0"
   ) {
     try {
-      reindexAfterSync(parsed.hqRoot);
-    } catch {
+      reindexAfterSync(parsed.hqRoot, {
+        log: ({ event, message, err, context }) =>
+          reportDiagnostic({
+            component: "qmd-reindex",
+            event,
+            message,
+            err,
+            context: { hqRoot: parsed.hqRoot, ...(context ?? {}) },
+          }),
+      });
+    } catch (err) {
+      reportDiagnostic({
+        component: "qmd-reindex",
+        event: "runner.qmd_reindex.failed",
+        message: "post-sync qmd reindex threw",
+        err,
+        context: { hqRoot: parsed.hqRoot },
+      });
       // Defensive: reindexAfterSync already swallows internally.
     }
   }
@@ -1113,7 +1230,14 @@ export async function runRunner(
   if (process.env.HQ_CONFLICT_PRUNE_ON_SYNC !== "0") {
     try {
       pruneConflictIndex(parsed.hqRoot);
-    } catch {
+    } catch (err) {
+      reportDiagnostic({
+        component: "conflict-index",
+        event: "runner.conflict_index.prune_failed",
+        message: "post-sync conflict index prune failed",
+        err,
+        context: { hqRoot: parsed.hqRoot },
+      });
       // Defensive: a prune failure must never affect the sync outcome.
     }
   }

package/src/cli/share.ts

@@ -888,15 +888,6 @@ async function createPushRunContext(options: ShareOptions): Promise<PushRunConte
   let propagateDeletePolicy: DeletePolicy =
     options.propagateDeletePolicy ?? "owned-only";
   const baseEmit = options.onEvent ?? defaultConsoleLogger;
-  // Mirror push progress into the shared cross-process snapshot (see sync.ts).
-  const recordProgress = createSyncProgressRecorder({
-    company: company ?? null,
-    phase: "push",
-  });
-  const emit: ShareEmit = (event) => {
-    baseEmit(event);
-    recordProgress(event);
-  };
 
   if (vaultConfig && entityContext) {
     throw new Error(
@@ -928,6 +919,21 @@ async function createPushRunContext(options: ShareOptions): Promise<PushRunConte
     propagateDeletePolicy = "currency-gated";
   }
 
+  // Mirror push progress into the shared cross-process snapshot (see sync.ts).
+  // Record the friendly company slug, or null for the personal vault so the
+  // menubar shows "Personal" — never the raw prs_/cmp_ UID.
+  const recordProgress = createSyncProgressRecorder({
+    company:
+      ctx.uid.startsWith("prs_") || options.personalMode === true
+        ? null
+        : ctx.slug,
+    phase: "push",
+  });
+  const emit: ShareEmit = (event) => {
+    baseEmit(event);
+    recordProgress(event);
+  };
+
   const syncRoot = options.personalMode === true
     ? hqRoot
     : path.join(hqRoot, "companies", ctx.slug);

package/src/cli/sync.test.ts

@@ -46,6 +46,7 @@ vi.mock("./reindex.js", () => ({
 import { sync, reportNewFilesToNotify } from "./sync.js";
 import * as s3Module from "../s3.js";
 import { reindex } from "./reindex.js";
+import { readSyncProgress } from "../sync-progress.js";
 
 const mockConfig: VaultServiceConfig = {
   apiUrl: "https://vault-api.test",
@@ -144,6 +145,22 @@ describe("sync", () => {
     expect(reindex).toHaveBeenCalledWith({ repoRoot: tmpDir, skipLock: true });
   });
 
+  it("records the company slug, not the input UID, in the shared progress snapshot", async () => {
+    // sync() is called with the company UID, but the menubar popover must show
+    // the friendly slug — so the producer records ctx.slug, never the raw UID.
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: "docs/x.md", size: 10, lastModified: new Date(), etag: '"x"' },
+    ]);
+    await sync({
+      company: "cmp_01ABCDEF",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+    const snap = readSyncProgress();
+    expect(snap).not.toBeNull();
+    expect(snap!.company).toBe("acme"); // ctx.slug, not "cmp_01ABCDEF"
+  });
+
   it("F15: public sync entrypoint refuses an already-held operation lock", async () => {
     process.env.HQ_OP_LOCK_TIMEOUT = "0";
     const lockPath = lockPathFor(tmpDir);

package/src/cli/sync.ts

@@ -658,6 +658,23 @@ function logNotifyFailure(err: unknown): void {
   }
 }
 
+/** Log a non-fatal post-sync maintenance failure without changing sync state. */
+function logPostSyncMaintenanceFailure(
+  task: string,
+  hqRoot: string,
+  err: unknown,
+): void {
+  try {
+    console.error(
+      `[hq-sync] ${task} failed (non-fatal; hqRoot=${hqRoot}): ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  } catch {
+    // swallow — logging must never break sync
+  }
+}
+
 /**
  * Sync (pull) all allowed files from the entity vault.
  */
@@ -710,17 +727,6 @@ async function syncWithOperationLockHeld(
 async function buildPullContext(options: SyncOptions): Promise<PullRunContext> {
   const { company, vaultConfig, hqRoot } = options;
   const baseEmit = options.onEvent ?? defaultConsoleLogger;
-  // Mirror every progress event into the shared cross-process snapshot so the
-  // menubar shows live progress for THIS sync regardless of who launched it
-  // (auto-sync / Sync Now / CLI). Best-effort; never affects the sync.
-  const recordProgress = createSyncProgressRecorder({
-    company: company ?? null,
-    phase: "pull",
-  });
-  const emit: SyncEventEmitter = (event) => {
-    baseEmit(event);
-    recordProgress(event);
-  };
 
   const companyRef = company ?? resolveActiveCompany(hqRoot);
   if (!companyRef) {
@@ -738,6 +744,20 @@ async function buildPullContext(options: SyncOptions): Promise<PullRunContext> {
   const journalSlug = options.journalSlug ?? ctx.slug;
   const startedAt = new Date().toISOString();
 
+  // Mirror every progress event into the shared cross-process snapshot so the
+  // menubar shows live progress for THIS sync regardless of who launched it
+  // (auto-sync / Sync Now / CLI). Record the friendly company slug (e.g.
+  // "indigo") — or null for the personal vault so the menubar shows "Personal"
+  // — never the raw prs_/cmp_ UID. Best-effort; never affects the sync.
+  const recordProgress = createSyncProgressRecorder({
+    company: options.personalMode === true ? null : ctx.slug,
+    phase: "pull",
+  });
+  const emit: SyncEventEmitter = (event) => {
+    baseEmit(event);
+    recordProgress(event);
+  };
+
   if (journalSlug === PERSONAL_VAULT_JOURNAL_SLUG) migratePersonalVaultJournal();
   const journal = migrateToV2(readJournal(journalSlug));
   gcTombstones(journal, Date.now());
@@ -1466,7 +1486,8 @@ function finalizePullRun(
   if (!run.options.skipReindex && changedOnDisk) {
     try {
       reindex({ repoRoot: run.hqRoot, skipLock: true });
-    } catch {
+    } catch (err) {
+      logPostSyncMaintenanceFailure("post-sync reindex", run.hqRoot, err);
       // best-effort: a post-sync refresh failure never fails the sync
     }
   }

package/src/qmd-reindex.ts

@@ -56,6 +56,13 @@ export interface ReindexOptions {
   readCompanies?: (companiesDir: string) => string[];
   /** Returns true if the knowledge dir has at least one indexable .md file. */
   hasIndexableMarkdown?: (knowledgeDir: string) => boolean;
+  /** Optional diagnostic sink for unexpected swallowed failures. */
+  log?: (diagnostic: {
+    event: string;
+    message: string;
+    err: unknown;
+    context?: Record<string, unknown>;
+  }) => void;
 }
 
 /**
@@ -110,7 +117,17 @@ export function reindexAfterSync(
       const embed = exec(["embed"]);
       result.embedded = embed.status === 0;
     }
-  } catch {
+  } catch (err) {
+    try {
+      opts.log?.({
+        event: "runner.qmd_reindex.internal_failed",
+        message: "post-sync qmd reindex failed",
+        err,
+        context: { hqRoot },
+      });
+    } catch {
+      /* diagnostics must never affect sync */
+    }
     // Reindex is best-effort; the sync result is authoritative. Swallow.
   }