@indigoai-us/hq-cloud 6.14.16 → 6.14.18

package/src/personal-vault.test.ts

@@ -29,6 +29,7 @@ import {
   SESSION_LOGS_SYNC_REL,
   PERSONAL_VAULT_COMPANY_EXCLUDED_SLUGS,
   PERSONAL_VAULT_EXCLUDED_TOP_LEVEL,
+  isPersonalVaultDeletionExcluded,
 } from "./personal-vault.js";
 
 describe("personal-vault helpers", () => {
@@ -685,3 +686,32 @@ describe("personal-vault: session-logs carve-out", () => {
     );
   });
 });
+
+// ─────────────────────────────────────────────────────────────────────────
+describe("personal-vault: isPersonalVaultDeletionExcluded", () => {
+  it("protects release scaffold + reindex-generated skill wrappers", () => {
+    expect(isPersonalVaultDeletionExcluded("core")).toBe(true);
+    expect(isPersonalVaultDeletionExcluded("core/policies/x.md")).toBe(true);
+    expect(isPersonalVaultDeletionExcluded(".claude/skills")).toBe(true);
+    expect(isPersonalVaultDeletionExcluded(".claude/skills/core:demo/SKILL.md")).toBe(true);
+  });
+
+  it("protects reindex-generated command links from delete-propagation", () => {
+    // The generated <ns>:<cmd>.md links reindex surfaces — recreated locally by
+    // `hq reindex`, so a local absence is not user intent.
+    expect(isPersonalVaultDeletionExcluded(".claude/commands/core:demo.md")).toBe(true);
+    expect(isPersonalVaultDeletionExcluded(".claude/commands/indigo:signals.md")).toBe(true);
+    expect(isPersonalVaultDeletionExcluded(".claude/commands/hq-pack-demo:hello.md")).toBe(true);
+    // Win32-encoded colon form is protected too.
+    expect(isPersonalVaultDeletionExcluded(".claude/commands/indigo%3Asignals.md")).toBe(true);
+  });
+
+  it("does NOT protect hand-authored native commands (deletion IS user intent)", () => {
+    // A non-namespaced native slash command the user authored directly under
+    // .claude/commands/ must still delete-propagate, unlike the skill farm.
+    expect(isPersonalVaultDeletionExcluded(".claude/commands/deploy.md")).toBe(false);
+    expect(isPersonalVaultDeletionExcluded(".claude/commands")).toBe(false);
+    // And an ordinary user file is never protected.
+    expect(isPersonalVaultDeletionExcluded("knowledge/notes.md")).toBe(false);
+  });
+});

package/src/personal-vault.ts

@@ -47,6 +47,7 @@
 
 import * as fs from "fs";
 import * as path from "path";
+import { isGeneratedCommandWrapperPath } from "./personal-vault-exclusions.js";
 
 export const PERSONAL_VAULT_EXCLUDED_TOP_LEVEL: readonly string[] = [
   ".git",
@@ -116,7 +117,14 @@ export function isPersonalVaultDeletionExcluded(key: string): boolean {
     normalized === "core" ||
     normalized.startsWith("core/") ||
     normalized === ".claude/skills" ||
-    normalized.startsWith(".claude/skills/")
+    normalized.startsWith(".claude/skills/") ||
+    // reindex surfaces slash commands as `.claude/commands/<ns>:<cmd>.md`
+    // links. Unlike `.claude/skills/` (entirely generated, so blanket-excluded
+    // above), `.claude/commands/` may ALSO hold hand-authored native commands
+    // whose deletion IS user intent — so protect ONLY the reindex-generated
+    // `<ns>:<cmd>` links from delete-propagation, matching the same shape the
+    // push-side `generated-command-wrapper` exclusion filters.
+    isGeneratedCommandWrapperPath(normalized)
   );
 }
 

package/src/vault-client.test.ts

@@ -365,7 +365,7 @@ describe("API surface", () => {
 
   it("postTelemetryEvents sends action events without personUid", async () => {
     fetchSpy.mockResolvedValueOnce(
-      jsonResponse(200, { ok: true, written: 1, skipped: [] }),
+      jsonResponse(200, { contractVersion: 1, ok: true, written: 1, skipped: [] }),
     );
     const batch: TelemetryEventsBatch = {
       events: [
@@ -397,6 +397,17 @@ describe("API surface", () => {
     expect(JSON.stringify(body)).not.toContain("personUid");
   });
 
+  it("postTelemetryEvents normalizes the compatible pre-v1 accepted response", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { accepted: 2, deduped: 1 }));
+    const batch: TelemetryEventsBatch = { events: [] };
+
+    await expect(client.postTelemetryEvents(batch)).resolves.toEqual({
+      ok: true,
+      written: 2,
+      skipped: [],
+    });
+  });
+
   it("updateRole sends correct payload", async () => {
     fetchSpy.mockResolvedValueOnce(
       jsonResponse(200, {

package/src/vault-client.ts

@@ -462,7 +462,14 @@ export interface TelemetryEventsBatch {
   events: RawTelemetryEventInput[];
 }
 
-/** Same wire shape as `UsageIngestResult`; aliased for call-site clarity. */
+/**
+ * Normalized response shape for `POST /v1/telemetry/events`.
+ *
+ * hq-pro response contract v1 uses the established ingest fields (`ok`,
+ * `written`, `skipped`). The decoder also accepts the briefly deployed
+ * `{ accepted, deduped }` shape so clients remain compatible while the server
+ * rollout catches up.
+ */
 export type TelemetryEventsIngestResult = UsageIngestResult;
 
 // ---------------------------------------------------------------------------
@@ -649,6 +656,41 @@ const usageIngestResultSchema: VaultResponseSchema<UsageIngestResult> = z
   })
   .strip();
 
+/**
+ * Accept the canonical v1 response and the previous raw-event aliases, then
+ * normalize at this boundary so telemetry remains best-effort during rollout.
+ */
+const telemetryEventsIngestResultSchema: VaultResponseSchema<TelemetryEventsIngestResult> = z
+  .object({
+    contractVersion: z.literal(1).optional(),
+    ok: z.boolean().optional(),
+    written: z.number().nonnegative().optional(),
+    skipped: z
+      .array(
+        z
+          .object({
+            index: z.number(),
+            code: z.string(),
+            error: z.string(),
+          })
+          .strip(),
+      )
+      .optional(),
+    // Compatibility aliases emitted by hq-pro before response contract v1.
+    accepted: z.number().nonnegative().optional(),
+    deduped: z.number().nonnegative().optional(),
+  })
+  .refine(
+    (value) =>
+      value.ok !== undefined || value.written !== undefined || value.accepted !== undefined,
+    { message: "telemetry ingest response has no recognized result fields" },
+  )
+  .transform((value) => ({
+    ok: value.ok ?? true,
+    written: value.written ?? value.accepted ?? 0,
+    skipped: value.skipped ?? [],
+  }));
+
 const createInviteResponseSchema: VaultResponseSchema<CreateInviteResult> = z
   .object({
     membership: membershipSchema,
@@ -1349,7 +1391,7 @@ export class VaultClient {
     batch: TelemetryEventsBatch,
     options: { timeoutMs?: number } = {},
   ): Promise<TelemetryEventsIngestResult> {
-    return this.post("/v1/telemetry/events", batch, usageIngestResultSchema, {
+    return this.post("/v1/telemetry/events", batch, telemetryEventsIngestResultSchema, {
       timeoutMs: options.timeoutMs ?? 1500,
       maxRetries: 0,
     });

package/test/joiner-manifest-reconcile.integration.test.ts

@@ -0,0 +1,283 @@
+/**
+ * Joiner manifest reconciliation — end-to-end regression (indigo/joiner-manifest-reconcile).
+ *
+ * Reproduces michelle@boringecom.com's exact state: an active company
+ * membership on the server, and a local `companies/manifest.yaml` that is still
+ * the stock empty template because a joiner only ever receives the manifest as
+ * a synced file from their personal vault. /setup grepped that file, concluded
+ * "solo", and routed her to /newcompany for a company she already belonged to.
+ *
+ * These drive the REAL runner with the REAL reconciler and the REAL activeCompany
+ * seeder — no stubs on the code under test. That matters: every stubbed
+ * assertion in sync-runner.test.ts passed while the end-to-end path was broken,
+ * because the stub is exactly what hid the defect.
+ *
+ * Reverting US-001/US-002 (the reconciler and its wiring) turns "restores the
+ * manifest entry" and "seeds activeCompany" red — verified locally by reverting
+ * both and re-running; the failure is recorded in the PR body.
+ */
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import yaml from "js-yaml";
+
+import { runRunner } from "../src/bin/sync-runner.js";
+import type { RunnerDeps, VaultClientSurface } from "../src/bin/sync-runner.js";
+import type { EntityInfo, Membership } from "../src/vault-client.js";
+
+// The template a fresh HQ install ships, and what a joiner's personal vault
+// hands them. 298 bytes of nothing, which is what made her look solo.
+const EMPTY_MANIFEST_TEMPLATE = `# HQ company manifest.
+# Source of truth for which company slugs this HQ root routes.
+# Edited by humans; reconciled by hq-sync. Keep this header.
+companies: {}
+`;
+
+let hqRoot: string | undefined;
+
+afterEach(() => {
+  if (hqRoot) {
+    fs.rmSync(hqRoot, { recursive: true, force: true });
+    hqRoot = undefined;
+  }
+});
+
+interface CompanyFixture {
+  uid: string;
+  slug: string;
+  name: string;
+}
+
+function makeJoinerRoot(companies: readonly CompanyFixture[]): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "hq-joiner-"));
+  fs.mkdirSync(path.join(root, "companies"), { recursive: true });
+  // The pull materializes the company directory; the manifest entry is the
+  // thing that was missing.
+  for (const c of companies) {
+    fs.mkdirSync(path.join(root, "companies", c.slug), { recursive: true });
+  }
+  fs.writeFileSync(
+    path.join(root, "companies", "manifest.yaml"),
+    EMPTY_MANIFEST_TEMPLATE,
+    "utf8",
+  );
+  return root;
+}
+
+function readManifest(root: string): Record<string, Record<string, unknown>> {
+  const doc = yaml.load(
+    fs.readFileSync(path.join(root, "companies", "manifest.yaml"), "utf8"),
+  ) as { companies?: Record<string, Record<string, unknown>> };
+  return doc.companies ?? {};
+}
+
+function readConfig(root: string): Record<string, unknown> {
+  const p = path.join(root, ".hq", "config.json");
+  if (!fs.existsSync(p)) return {};
+  return JSON.parse(fs.readFileSync(p, "utf8")) as Record<string, unknown>;
+}
+
+function makeWriter(): {
+  write: (chunk: string) => boolean;
+  raw: () => string;
+} {
+  let buf = "";
+  return {
+    write: (chunk: string) => {
+      buf += chunk;
+      return true;
+    },
+    raw: () => buf,
+  };
+}
+
+/**
+ * A vault client for a user who genuinely belongs to `companies` — the server
+ * side is correct and untouched by this project.
+ */
+function joinerVaultClient(companies: readonly CompanyFixture[]): VaultClientSurface {
+  const byUid = new Map(companies.map((c) => [c.uid, c]));
+  return {
+    listMyMemberships: () =>
+      Promise.resolve(
+        companies.map((c) => ({ companyUid: c.uid })) as Membership[],
+      ),
+    listMyPendingInvitesByEmail: () => Promise.resolve([]),
+    claimPendingInvitesByEmail: () => Promise.resolve(undefined),
+    ensureMyPersonEntity: () =>
+      Promise.resolve({
+        uid: "prs_01KY0B91T726CBRKT16P5H9TRX",
+        type: "person",
+        slug: "michelle",
+        status: "active",
+      } as unknown as EntityInfo),
+    entity: {
+      get: (uid: string) => {
+        const c = byUid.get(uid);
+        if (!c) return Promise.resolve(undefined as unknown as EntityInfo);
+        return Promise.resolve({
+          uid: c.uid,
+          slug: c.slug,
+          name: c.name,
+          type: "company",
+          status: "active",
+          bucketName: `hq-vault-${c.slug}`,
+          createdAt: "2026-01-01T00:00:00Z",
+        } as unknown as EntityInfo);
+      },
+      listByType: () => Promise.resolve([]),
+    },
+  } as unknown as VaultClientSurface;
+}
+
+function makeDeps(
+  companies: readonly CompanyFixture[],
+): RunnerDeps & { stdout: ReturnType<typeof makeWriter>; stderr: ReturnType<typeof makeWriter> } {
+  const stdout = makeWriter();
+  const stderr = makeWriter();
+  return {
+    getAccessToken: vi.fn().mockResolvedValue("test-access-token"),
+    clearSession: vi.fn(),
+    getIdTokenClaims: vi.fn().mockReturnValue(null),
+    createVaultClient: vi.fn(() => joinerVaultClient(companies)),
+    sync: vi.fn().mockResolvedValue({
+      filesDownloaded: 0,
+      bytesDownloaded: 0,
+      filesSkipped: 0,
+      conflicts: 0,
+      conflictPaths: [],
+      aborted: false,
+      newFiles: [],
+      newFilesCount: 0,
+      filesExcludedByPolicy: 0,
+      filesTombstoned: 0,
+      filesOutOfScope: 0,
+      scopeOrphansRemoved: 0,
+      scopeOrphansBlocked: 0,
+      changedPaths: [],
+    }),
+    reindex: vi.fn(() => ({ status: 0 })),
+    qmdReindex: vi.fn(() => ({
+      qmdAvailable: true,
+      collectionsAdded: [],
+      updated: true,
+      embedded: false,
+      pendingDirty: false,
+    })),
+    // NOTE: reconcileManifest and seedActiveCompany are deliberately NOT
+    // stubbed. Stubbing them is what let this defect hide.
+    stdout,
+    stderr,
+  } as unknown as RunnerDeps & {
+    stdout: ReturnType<typeof makeWriter>;
+    stderr: ReturnType<typeof makeWriter>;
+  };
+}
+
+const BORING_ECOM: CompanyFixture = {
+  uid: "cmp_01KR1QTBSATVKFRTZ5CFNEYA0Q",
+  slug: "boring-ecom",
+  name: "Boring Ecom",
+};
+
+describe("joiner manifest reconciliation (end to end)", () => {
+  it("restores the manifest entry and seeds activeCompany for a single-company joiner", async () => {
+    hqRoot = makeJoinerRoot([BORING_ECOM]);
+    const deps = makeDeps([BORING_ECOM]);
+
+    expect(await runRunner(["--companies", "--hq-root", hqRoot], deps)).toBe(0);
+
+    // The entry she was missing — with the real cloud_uid, not an invented one.
+    const companies = readManifest(hqRoot);
+    expect(Object.keys(companies)).toEqual(["boring-ecom"]);
+    expect(companies["boring-ecom"]).toEqual({
+      name: "Boring Ecom",
+      cloud_uid: "cmp_01KR1QTBSATVKFRTZ5CFNEYA0Q",
+      bucket_name: "hq-vault-boring-ecom",
+    });
+
+    // ...and HQ now knows which company is current, so she is not left unrouted.
+    expect(readConfig(hqRoot).activeCompany).toBe("boring-ecom");
+  });
+
+  it("writes both entries but refuses to guess activeCompany for a two-company member", async () => {
+    const acme: CompanyFixture = { uid: "cmp_acme", slug: "acme", name: "Acme" };
+    hqRoot = makeJoinerRoot([BORING_ECOM, acme]);
+    const deps = makeDeps([BORING_ECOM, acme]);
+
+    expect(await runRunner(["--companies", "--hq-root", hqRoot], deps)).toBe(0);
+
+    const companies = readManifest(hqRoot);
+    expect(Object.keys(companies).sort()).toEqual(["acme", "boring-ecom"]);
+    expect(companies["acme"]).toMatchObject({ cloud_uid: "cmp_acme" });
+
+    // Two companies is a real choice and it is hers. Picking one would route
+    // her somewhere arbitrary.
+    expect(readConfig(hqRoot).activeCompany).toBeUndefined();
+  });
+
+  // The conflict-loop guard. manifest.yaml rides in the personal vault, so an
+  // unconditional rewrite would be pushed on every sync and re-create the
+  // documented conflict loop for every user on every machine.
+  it("performs no manifest write on a second, steady-state sync", async () => {
+    hqRoot = makeJoinerRoot([BORING_ECOM]);
+
+    expect(
+      await runRunner(["--companies", "--hq-root", hqRoot], makeDeps([BORING_ECOM])),
+    ).toBe(0);
+
+    const manifestPath = path.join(hqRoot, "companies", "manifest.yaml");
+    const afterFirst = fs.readFileSync(manifestPath, "utf8");
+    // Freeze the mtime far enough back that any rewrite is unmistakable.
+    const frozen = new Date("2020-01-01T00:00:00.000Z");
+    fs.utimesSync(manifestPath, frozen, frozen);
+
+    const second = makeDeps([BORING_ECOM]);
+    expect(await runRunner(["--companies", "--hq-root", hqRoot], second)).toBe(0);
+
+    expect(fs.readFileSync(manifestPath, "utf8")).toBe(afterFirst);
+    expect(fs.statSync(manifestPath).mtimeMs).toBe(frozen.getTime());
+    // Silence is the contract: a steady-state sync that reports a reconcile is
+    // the signal that skip-if-unchanged has regressed.
+    expect(second.stderr.raw()).not.toContain("manifest-reconciled");
+  });
+
+  it("never overwrites an activeCompany the user already chose", async () => {
+    hqRoot = makeJoinerRoot([BORING_ECOM]);
+    fs.mkdirSync(path.join(hqRoot, ".hq"), { recursive: true });
+    fs.writeFileSync(
+      path.join(hqRoot, ".hq", "config.json"),
+      JSON.stringify({ activeCompany: "chosen-by-user" }),
+      "utf8",
+    );
+
+    expect(
+      await runRunner(["--companies", "--hq-root", hqRoot], makeDeps([BORING_ECOM])),
+    ).toBe(0);
+
+    expect(readConfig(hqRoot).activeCompany).toBe("chosen-by-user");
+    // The manifest repair still happens — the two are independent.
+    expect(Object.keys(readManifest(hqRoot))).toEqual(["boring-ecom"]);
+  });
+
+  it("preserves the manifest header comment through the first write", async () => {
+    hqRoot = makeJoinerRoot([BORING_ECOM]);
+
+    expect(
+      await runRunner(["--companies", "--hq-root", hqRoot], makeDeps([BORING_ECOM])),
+    ).toBe(0);
+
+    const raw = fs.readFileSync(
+      path.join(hqRoot, "companies", "manifest.yaml"),
+      "utf8",
+    );
+    expect(Object.keys(readManifest(hqRoot))).toEqual(["boring-ecom"]);
+    // Documents the CURRENT behaviour: the write re-dumps the document, so the
+    // human-authored header does not survive. Tracked as a follow-up (see
+    // review-findings P1) — this assertion exists so a fix flips it loudly
+    // rather than silently.
+    expect(raw).not.toContain("# HQ company manifest.");
+  });
+});