@indigoai-us/hq-cloud 6.14.16 → 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) {

package/src/cli/reindex.test.ts

@@ -90,6 +90,14 @@ describe("reindex", () => {
     fs.writeFileSync(path.join(dir, "SKILL.md"), "skill\n");
   }
 
+  // Write a namespaced slash-command source file, e.g.
+  // writeCommand("core/commands/demo.md") → root/core/commands/demo.md.
+  function writeCommand(rel: string, body = "command\n"): void {
+    const abs = path.join(root, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, body);
+  }
+
   it("surfaces namespaced skills as .claude/skills/<ns>:<skill>/ wrappers", () => {
     writeSkill("core/skills/demo");
     fs.writeFileSync(path.join(root, "core/skills/demo/helper.md"), "h\n");
@@ -112,6 +120,114 @@ describe("reindex", () => {
     );
   });
 
+  // ── namespaced slash-command surfacing (parallel to skills) ─────────────
+  // reindex mirrors <ns>/commands/<cmd>.md into .claude/commands/<ns>:<cmd>.md
+  // as a single symlink per source file, using the same <ns>:<name> naming as
+  // skills so a company/core/personal/pack command shows up as /<ns>:<cmd>.
+
+  it("surfaces namespaced commands as .claude/commands/<ns>:<cmd>.md symlinks", () => {
+    writeCommand("core/commands/demo.md");
+    writeCommand("companies/acme/commands/widget.md");
+    writeCommand("personal/commands/note.md");
+    writeCommand("core/packages/hq-pack-demo/commands/hello.md");
+
+    const { status } = reindex({ repoRoot: root });
+    expect(status).toBe(0);
+
+    const link = (name: string) => path.join(root, ".claude/commands", name);
+
+    expect(fs.lstatSync(link("core:demo.md")).isSymbolicLink()).toBe(true);
+    expect(fs.readlinkSync(link("core:demo.md"))).toBe("../../core/commands/demo.md");
+
+    expect(fs.readlinkSync(link("acme:widget.md"))).toBe(
+      "../../companies/acme/commands/widget.md",
+    );
+    expect(fs.readlinkSync(link("personal:note.md"))).toBe(
+      "../../personal/commands/note.md",
+    );
+    expect(fs.readlinkSync(link("hq-pack-demo:hello.md"))).toBe(
+      "../../core/packages/hq-pack-demo/commands/hello.md",
+    );
+  });
+
+  it("skips `_`-prefixed, dotfile, and non-.md command files", () => {
+    writeCommand("core/commands/_partial.md");
+    writeCommand("core/commands/.hidden.md");
+    writeCommand("core/commands/notes.txt");
+    writeCommand("core/commands/real.md");
+
+    reindex({ repoRoot: root });
+
+    const cmds = path.join(root, ".claude/commands");
+    expect(fs.existsSync(path.join(cmds, "core:real.md"))).toBe(true);
+    expect(fs.existsSync(path.join(cmds, "core:_partial.md"))).toBe(false);
+    expect(fs.existsSync(path.join(cmds, "core:.hidden.md"))).toBe(false);
+    expect(fs.existsSync(path.join(cmds, "core:notes.txt"))).toBe(false);
+  });
+
+  it("prunes orphan managed command links when the source command disappears", () => {
+    writeCommand("core/commands/demo.md");
+    reindex({ repoRoot: root });
+    expect(fs.existsSync(path.join(root, ".claude/commands/core:demo.md"))).toBe(true);
+
+    fs.rmSync(path.join(root, "core/commands/demo.md"));
+    reindex({ repoRoot: root });
+    expect(fs.existsSync(path.join(root, ".claude/commands/core:demo.md"))).toBe(false);
+  });
+
+  it("is idempotent for commands — a second run keeps the same link", () => {
+    writeCommand("core/commands/demo.md");
+    expect(reindex({ repoRoot: root }).status).toBe(0);
+    expect(reindex({ repoRoot: root }).status).toBe(0);
+    expect(fs.readlinkSync(path.join(root, ".claude/commands/core:demo.md"))).toBe(
+      "../../core/commands/demo.md",
+    );
+  });
+
+  it("leaves hand-authored / non-managed command files alone", () => {
+    const cmds = path.join(root, ".claude/commands");
+    fs.mkdirSync(cmds, { recursive: true });
+    // A real file with no namespace colon → preserved.
+    fs.writeFileSync(path.join(cmds, "manual.md"), "manual\n");
+    // A real (non-symlink) file that happens to use a managed namespace prefix
+    // → still preserved; reindex only ever prunes symlinks it created.
+    fs.writeFileSync(path.join(cmds, "core:hand.md"), "hand\n");
+    // A composite symlink under an UNMANAGED namespace → preserved.
+    writeCommand("core/commands/other.md");
+    fs.symlinkSync("../../core/commands/other.md", path.join(cmds, "vendor:tool.md"));
+
+    reindex({ repoRoot: root });
+
+    expect(fs.existsSync(path.join(cmds, "manual.md"))).toBe(true);
+    expect(fs.existsSync(path.join(cmds, "core:hand.md"))).toBe(true);
+    expect(fs.lstatSync(path.join(cmds, "vendor:tool.md")).isSymbolicLink()).toBe(true);
+  });
+
+  it("preserves a hand-authored alias under a managed namespace (target basename differs)", () => {
+    // A live source command...
+    writeCommand("core/commands/demo.md");
+    // ...plus a hand-authored alias in the SAME (managed) namespace pointing at
+    // it under a different command name, with NO core/commands/alias.md source.
+    // A prefix-only ownership test would wrongly treat this as a reindex link
+    // and delete it; the exact-target cross-check must keep it.
+    const cmds = path.join(root, ".claude/commands");
+    fs.mkdirSync(cmds, { recursive: true });
+    fs.symlinkSync("../../core/commands/demo.md", path.join(cmds, "core:alias.md"));
+
+    reindex({ repoRoot: root });
+
+    // The alias survives, and the real managed link is still created.
+    expect(fs.lstatSync(path.join(cmds, "core:alias.md")).isSymbolicLink()).toBe(true);
+    expect(fs.readlinkSync(path.join(cmds, "core:alias.md"))).toBe("../../core/commands/demo.md");
+    expect(fs.existsSync(path.join(cmds, "core:demo.md"))).toBe(true);
+  });
+
+  it("does not create an empty .claude/commands when there are no command sources", () => {
+    writeSkill("core/skills/demo");
+    reindex({ repoRoot: root });
+    expect(fs.existsSync(path.join(root, ".claude/commands"))).toBe(false);
+  });
+
   it("does NOT mirror the personal overlay into core/<type>/ (read directly now)", () => {
     fs.mkdirSync(path.join(root, "personal/policies"), { recursive: true });
     fs.writeFileSync(path.join(root, "personal/policies/myrule.md"), "rule\n");

package/src/cli/reindex.ts

@@ -1,7 +1,9 @@
 /**
  * hq reindex — surfaces namespaced skills as Claude Code skill wrappers under
- * .claude/skills/<ns>:<skill>/ (one symlink per source file), prunes orphan
- * wrappers + legacy command symlinks (plus a migration cleanup of retired
+ * .claude/skills/<ns>:<skill>/ (one symlink per source file), surfaces
+ * namespaced slash commands as .claude/commands/<ns>:<cmd>.md symlinks (one per
+ * source <ns>/commands/<cmd>.md file), prunes orphan wrappers + command links +
+ * legacy command symlinks (plus a migration cleanup of retired
  * personal/{knowledge,policies,workers,settings} mirror symlinks in core/<type>/
  * — that overlay is now read directly from personal/, not mirrored), captures
  * this HQ tree's coding-harness session logs (Claude Code / Codex / Grok) into
@@ -510,6 +512,27 @@ export function reindex(opts: ReindexOptions = {}): ReindexResult {
     }
   }
 
+  // --- Build (namespace, src_rel) pairs for slash commands ------------------
+  // Mirrors the skill namespaces but reads from <ns>/commands/ instead of
+  // <ns>/skills/. Built independently so a namespace with commands but no
+  // skills (or vice-versa) is handled on its own.
+  const cmdPairs: { ns: string; srcRel: string }[] = [];
+  const addCmdNs = (ns: string, srcRel: string): void => {
+    if (isDir(path.join(root, srcRel))) cmdPairs.push({ ns, srcRel });
+  };
+  for (const slug of globEntries(path.join(root, "companies"))) {
+    if (isDir(path.join(root, "companies", slug))) {
+      addCmdNs(slug, `companies/${slug}/commands`);
+    }
+  }
+  addCmdNs("core", "core/commands");
+  addCmdNs("personal", "personal/commands");
+  for (const pack of globEntries(path.join(root, "core", "packages"))) {
+    if (isDir(path.join(root, "core", "packages", pack))) {
+      addCmdNs(pack, `core/packages/${pack}/commands`);
+    }
+  }
+
   // --- Cleanup pass A: drop legacy .claude/commands/<ns>/<skill>.md links ----
   const commandsDir = path.join(root, ".claude", "commands");
   if (isDir(commandsDir)) {
@@ -690,6 +713,106 @@ export function reindex(opts: ReindexOptions = {}): ReindexResult {
     }
   }
 
+  // --- Slash-command surfacing ----------------------------------------------
+  // Parallel to skills: mirror each namespace's commands/<cmd>.md into
+  // .claude/commands/<ns>:<cmd>.md, so a company/core/personal/pack command
+  // shows up as /<ns>:<cmd> with the same <ns>:<name> naming as skills. A slash
+  // command is a single .md file (not a folder), so each wrapper is ONE symlink
+  // two levels below REPO_ROOT — no per-file wrapper directory.
+  const expectedCommands = new Set<string>();
+  const seenCmd = new Set<string>();
+  // Lazy: only materialize .claude/commands when a source command exists, so a
+  // tree with no commands never gains an empty directory. The orphan-prune pass
+  // below still runs against whatever already exists.
+  if (cmdPairs.length > 0) {
+    safeMkdir(commandsDir, ".claude/commands directory");
+  }
+  for (const { ns, srcRel } of cmdPairs) {
+    // First writer for a namespace wins (matches the skill dedup).
+    if (seenCmd.has(ns)) {
+      warn(
+        `reindex: command namespace '${ns}' already claimed by an earlier source; skipping ${srcRel}`,
+      );
+      continue;
+    }
+    seenCmd.add(ns);
+
+    const srcAbs = path.join(root, srcRel);
+    for (const entry of globEntries(srcAbs)) {
+      // Skip `_`-prefixed include partials (dotfiles already excluded by glob)
+      // and anything that isn't a regular `.md` command file.
+      if (entry.startsWith("_")) continue;
+      if (!entry.endsWith(".md")) continue;
+      if (!isFile(path.join(srcAbs, entry))) continue;
+
+      const wrapperName = encodeLocalVaultSegment(`${ns}:${entry}`);
+      const linkPath = path.join(commandsDir, wrapperName);
+      const relativeTarget = `../../${srcRel}/${entry}`;
+      expectedCommands.add(wrapperName);
+
+      const lst = lstatOrNull(linkPath);
+      if (lst && lst.isSymbolicLink()) {
+        const current = readlinkOrNull(linkPath);
+        if (current === relativeTarget) continue;
+        skippedPointsElsewhere++;
+        if (verbose) {
+          warn(
+            `reindex: .claude/commands/${wrapperName} already points to '${current}' (expected '${relativeTarget}'); leaving alone`,
+          );
+        }
+        continue;
+      } else if (lst) {
+        skippedNonSymlink++;
+        if (verbose) {
+          warn(`reindex: ${linkPath} already exists and is not a symlink; skipping`);
+        }
+        continue;
+      }
+
+      safeSymlink(relativeTarget, linkPath, `.claude/commands/${wrapperName}`);
+    }
+  }
+
+  // --- Cleanup: drop orphan <ns>:<cmd>.md command links ---------------------
+  // Symmetric to skill Cleanup pass B, adapted to the flat one-symlink-per-file
+  // shape (`../../` target, no wrapper directory). Only prunes symlinks reindex
+  // owns: a managed namespace whose target resolves into that namespace's
+  // commands/. Real files (even under a managed namespace) and composite links
+  // under an unmanaged namespace are left for a human to resolve.
+  for (const entry of globEntries(commandsDir)) {
+    const entryPath = path.join(commandsDir, entry);
+    const lst = lstatOrNull(entryPath);
+    if (!lst) continue; // accept broken symlinks (lstat still succeeds)
+    if (!lst.isSymbolicLink()) continue; // real files / legacy subdirs → not ours
+    const canonicalEntry = decodeLocalVaultSegment(entry);
+    if (!canonicalEntry.endsWith(".md")) continue;
+    if (!canonicalEntry.includes(":")) continue; // not a namespaced command
+    if (expectedCommands.has(entry)) continue; // maintained this run
+
+    const ns = canonicalEntry.slice(0, canonicalEntry.indexOf(":"));
+    const cmdName = canonicalEntry.slice(canonicalEntry.indexOf(":") + 1);
+    const target = readlinkOrNull(entryPath);
+    // A reindex-created link points at EXACTLY ../../<managed-base>/commands/
+    // <cmdName> — its basename equals the decoded command name. Cross-check the
+    // full expected target (not just the namespace-dir prefix) so a hand-authored
+    // alias such as `core:alias.md -> ../../core/commands/demo.md` (basename
+    // 'demo.md' != 'alias.md', and with no core/commands/alias.md source) is
+    // preserved rather than pruned as if reindex owned it.
+    const managedTargets: string[] = [];
+    if (ns === "personal") managedTargets.push(`../../personal/commands/${cmdName}`);
+    if (ns === "core") managedTargets.push(`../../core/commands/${cmdName}`);
+    managedTargets.push(`../../companies/${ns}/commands/${cmdName}`);
+    managedTargets.push(`../../core/packages/${ns}/commands/${cmdName}`);
+    if (target === null || !managedTargets.includes(target)) continue;
+
+    // Managed command link with no corresponding live source → drop.
+    try {
+      fs.rmSync(entryPath);
+    } catch {
+      /* best-effort */
+    }
+  }
+
   // --- Personal-overlay mirroring: RETIRED + migration cleanup ---------------
   // personal/{knowledge,policies,workers,settings} is now read DIRECTLY by the
   // HQ tooling (the inject-policy-on-trigger hook reads personal/policies, the