@indigoai-us/hq-cloud 6.14.17 → 6.14.18

package/src/bin/sync-runner.ts

@@ -140,10 +140,18 @@ import {
   buildFanoutPlan,
   emitFanoutPlan,
   resolveMembershipsForRun,
+  type RunnerTarget,
+  type SetupNeededReason,
 } from "./sync-runner-planning.js";
+import {
+  seedActiveCompany,
+  type SeedActiveCompanyOptions,
+  type SeedActiveCompanyResult,
+} from "../active-company.js";
 import {
   reconcileCompanyManifest,
   type ManifestReconcileOptions,
+  type ManifestReconcileResult,
 } from "../manifest-reconcile.js";
 import { executeCompanyFanout } from "./sync-runner-company.js";
 import { rollupAllComplete } from "./sync-runner-rollup.js";
@@ -333,11 +341,28 @@ export { PERSONAL_VAULT_EXCLUDED_TOP_LEVEL, computePersonalVaultPaths };
  * specific company".
  */
 export type RunnerEvent =
-  | { type: "setup-needed" }
+  | {
+      /**
+       * The run cannot proceed. `reason` and `pendingInviteCount` are additive
+       * and optional by design: a consumer that only reads `type` behaves
+       * exactly as before, while /setup and /hq-sync can tell the user WHY they
+       * look solo — most usefully, that an invite is still waiting.
+       */
+      type: "setup-needed";
+      reason?: SetupNeededReason;
+      pendingInviteCount?: number;
+    }
   | { type: "auth-error"; message: string }
   | {
+      /**
+       * The resolved fanout plan. Carries whole `RunnerTarget`s: the runtime
+       * payload has always been the plan entries verbatim, so the previous
+       * `{uid, slug, name?}` declaration understated the wire contract (it
+       * already omitted `bucketName`, `personalMode`, and `journalSlug`).
+       * Consumers deserialize leniently and ignore fields they do not know.
+       */
       type: "fanout-plan";
-      companies: Array<{ uid: string; slug: string; name?: string }>;
+      companies: RunnerTarget[];
     }
   | ({
       /**
@@ -632,7 +657,9 @@ export interface RunnerDeps {
    */
   reconcileManifest?: (
     options: ManifestReconcileOptions,
-  ) => Promise<void>;
+  ) => Promise<ManifestReconcileResult>;
+  /** Internal test seam for `.hq/config.json` activeCompany seeding. */
+  seedActiveCompany?: (options: SeedActiveCompanyOptions) => SeedActiveCompanyResult;
   /** Internal: set when runRunner is invoked under the per-root operation lock. */
   operationLockAlreadyHeld?: boolean;
   /** Internal watch-loop result override; one-shot callers keep exit 0. */
@@ -698,10 +725,11 @@ async function runClaimDance(
   client: VaultClientSurface,
   claims: IdTokenClaims,
   stderr: { write: (chunk: string) => boolean | void },
-): Promise<void> {
+  reportDiagnostic: RunnerDiagnosticReporter = () => undefined,
+): Promise<number> {
   try {
     const pending = await client.listMyPendingInvitesByEmail();
-    if (pending.length === 0) return;
+    if (pending.length === 0) return 0;
 
     const displayName =
       claims.name ??
@@ -710,10 +738,15 @@ async function runClaimDance(
       "";
     const ownerSub = claims.sub ?? "";
     if (!ownerSub || !displayName) {
-      stderr.write(
-        "hq-sync-runner: skipping claim-dance — idToken missing sub/name\n",
-      );
-      return;
+      reportDiagnostic({
+        component: "claim-dance",
+        event: "runner.claim_dance.skipped",
+        message: "skipping claim-dance — idToken missing sub/name",
+        context: { pendingInviteCount: pending.length },
+      });
+      // The invites are real and still pending; the caller must be able to say
+      // so even though we could not claim them.
+      return pending.length;
     }
 
     const person = await client.ensureMyPersonEntity({
@@ -721,9 +754,19 @@ async function runClaimDance(
       displayName,
     });
     await client.claimPendingInvitesByEmail(person.uid);
+    return pending.length;
   } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    stderr.write(`hq-sync-runner: claim-dance skipped — ${msg}\n`);
+    // Non-throwing by contract: a claim-dance failure must never take down a
+    // sync. But it stops being invisible — a systematic failure here is exactly
+    // what makes a joiner look permanently solo.
+    reportDiagnostic({
+      component: "claim-dance",
+      event: "runner.claim_dance.skipped",
+      message: "claim-dance skipped",
+      err,
+      context: {},
+    });
+    return 0;
   }
 }
 
@@ -1276,11 +1319,18 @@ export async function runRunner(
       client,
       claims,
       stderr,
-      runClaimDance,
+      runClaimDance: (client, claims, stderr) =>
+        runClaimDance(client, claims, stderr, reportDiagnostic),
       listMemberships: listMembershipsWithRetry,
     });
     if (resolution.status === "setup-needed") {
-      emit({ type: "setup-needed" });
+      emit({
+        type: "setup-needed",
+        reason: resolution.reason,
+        ...(resolution.pendingInviteCount === undefined
+          ? {}
+          : { pendingInviteCount: resolution.pendingInviteCount }),
+      });
       return 0;
     }
     memberships = resolution.memberships;
@@ -1335,7 +1385,7 @@ export async function runRunner(
     return isTransientNetworkError(err) ? TRANSIENT_NETWORK_EXIT : 1;
   }
   if (targetPlan.status === "setup-needed") {
-    emit({ type: "setup-needed" });
+    emit({ type: "setup-needed", reason: targetPlan.reason });
     return 0;
   }
   const plan = targetPlan.plan;
@@ -1386,19 +1436,43 @@ export async function runRunner(
   // The personal-vault target runs last and can pull an older copy of the
   // manifest. Reconcile only after the entire pull fanout has settled so the
   // successfully materialized cloud directories restore their own entries.
-  if (parsed.direction !== "push") {
+  //
+  // `--companies` only. A single-company run (`--company <slug>`) and a
+  // `--personal` run both see just one leg of the fanout, so neither has the
+  // full picture the manifest is reconciled against; treating a partial view as
+  // authoritative is how entries get lost. A push-only pass materializes
+  // nothing new locally, so it has nothing to reconcile either.
+  if (parsed.companies && parsed.direction !== "push") {
+    const completedCompanySlugs = new Set(
+      Array.from(fanout.stateByCompany.entries())
+        .filter(([, state]) => state.status === "complete")
+        .map(([slug]) => slug),
+    );
+    // The personal vault is never a manifest entry. The reconciler filters it
+    // too, but that is its own internal invariant — excluding it here means
+    // the personal target is never even handed across the seam.
+    const companyTargets = plan.filter(
+      (target) => target.personalMode !== true && target.slug !== "personal",
+    );
     try {
-      const completedCompanySlugs = new Set(
-        Array.from(fanout.stateByCompany.entries())
-          .filter(([, state]) => state.status === "complete")
-          .map(([slug]) => slug),
-      );
-      await (deps.reconcileManifest ?? reconcileCompanyManifest)({
+      const result = await (deps.reconcileManifest ?? reconcileCompanyManifest)({
         hqRoot: parsed.hqRoot,
-        targets: plan,
+        targets: companyTargets,
         completedCompanySlugs,
-        getEntity: client.entity.get,
+        reportDiagnostic: (diagnostic) =>
+          reportDiagnostic({ component: "manifest-reconcile", ...diagnostic }),
       });
+      // Only on an actual write. A steady-state sync stays silent, so an
+      // unexpected diagnostic rate is itself the signal that skip-if-unchanged
+      // has regressed.
+      if (result.written) {
+        reportDiagnostic({
+          component: "manifest-reconcile",
+          event: "manifest-reconciled",
+          message: "restored company entries in companies/manifest.yaml",
+          context: { added: result.added, updated: result.updated },
+        });
+      }
     } catch (err) {
       reportDiagnostic({
         component: "manifest-reconcile",
@@ -1408,6 +1482,38 @@ export async function runRunner(
         context: { hqRoot: parsed.hqRoot },
       });
     }
+
+    // A joiner whose manifest entry was just restored still has nothing telling
+    // HQ which company is current. Seed it only when the answer cannot be wrong
+    // — deliberately its own try, so a manifest failure does not also cost the
+    // user their routing.
+    try {
+      const localCompanySlugs = companyTargets
+        .map((target) => target.slug)
+        .filter((slug) => completedCompanySlugs.has(slug));
+      const seeded = (deps.seedActiveCompany ?? seedActiveCompany)({
+        hqRoot: parsed.hqRoot,
+        companySlugs: localCompanySlugs,
+        reportDiagnostic: (diagnostic) =>
+          reportDiagnostic({ component: "active-company", ...diagnostic }),
+      });
+      if (seeded.written) {
+        reportDiagnostic({
+          component: "active-company",
+          event: "active-company-seeded",
+          message: "seeded activeCompany in .hq/config.json",
+          context: { activeCompany: seeded.activeCompany },
+        });
+      }
+    } catch (err) {
+      reportDiagnostic({
+        component: "active-company",
+        event: "runner.active_company.failed",
+        message: "seeding activeCompany failed",
+        err,
+        context: { hqRoot: parsed.hqRoot },
+      });
+    }
   }
 
   if (rollup.needsReindex) {