@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/cli/reindex.ts

@@ -1,979 +0,0 @@
-/**
- * hq reindex — surfaces namespaced skills as Claude Code skill wrappers under
- * .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
- * workspace/.session-logs/<harness>/, and regenerates the workers registry.
- *
- * The logic historically lived in a bundled bash script (scripts/reindex.sh)
- * that this module exec'd via `bash`. It is now implemented natively in
- * TypeScript so the package ships a single, testable code path with no runtime
- * dependency on a shipped shell script. Behaviour is preserved exactly: the
- * same skill wrappers, personal-overlay mirrors, legacy-symlink cleanup, and
- * idempotent re-runs as before. Historically the script ran directly as a
- * Claude Code hook inside hq-core (named "master-sync"); the hq-core hook
- * remains a thin shim over `hq reindex`.
- */
-import { spawnSync } from "child_process";
-import * as fs from "fs";
-import * as os from "os";
-import * as path from "path";
-import { readlinkOrNull } from "../lib/readlink-safe.js";
-import {
-  acquireOperationLock,
-  OperationLockedError,
-  OperationLockUnwritableError,
-  OPERATION_LOCKED_EXIT,
-  OPERATION_LOCK_UNWRITABLE_EXIT,
-  type LockHandle,
-} from "../operation-lock.js";
-import {
-  emitCloudTelemetry,
-  type CloudTelemetryClient,
-  type TelemetryClaims,
-} from "../telemetry-events.js";
-import { decodeLocalVaultSegment, encodeLocalVaultSegment } from "../local-path-codec.js";
-import { materializeLegacyKnowledgeRepos } from "./reindex-knowledge.js";
-
-export interface ReindexOptions {
-  /** HQ root to operate on. Defaults to process.cwd(). */
-  repoRoot?: string;
-  /**
-   * Skip reindex's own per-root "reindex"-scope lock. Internal callers
-   * (`sync()` / `rescue()`) run reindex inline at the tail of a pass they
-   * already serialize, and pass `true` so a standalone `hq reindex` holding the
-   * reindex lock never blocks the sync/rescue tail (reindex is idempotent and
-   * re-run every pass, so a benign overlap self-heals). Standalone callers
-   * (`hq reindex`, the reindex hook) leave it falsy so concurrent reindexes are
-   * mutually exclusive.
-   */
-  skipLock?: boolean;
-  /**
-   * Bounded wait (seconds) for the per-root "reindex"-scope lock when another
-   * reindex is already running. `0` → refuse immediately; omitted → inherit
-   * `HQ_OP_LOCK_TIMEOUT` / infinite wait. Ignored when `skipLock` is set.
-   *
-   * NB: reindex uses a lock scope SEPARATE from sync/rescue's "operation" lock,
-   * so a long-lived watch-mode sync-runner (which holds the operation lock for
-   * its whole lifetime) can never starve a standalone `hq reindex`
-   * (feedback_ed98d810). Standalone `hq reindex` waits by default, which is what
-   * a human running it wants; the hq-core reindex HOOK (Stop / PostToolUse)
-   * should set a small `HQ_OP_LOCK_TIMEOUT` (or `0`) so a hook fired while
-   * another reindex runs never blocks the interactive agent indefinitely.
-   */
-  lockTimeoutSec?: number;
-  /** Optional hq-pro ACTION telemetry sink. Omitted in tests/standalone hooks. */
-  telemetryClient?: CloudTelemetryClient | null;
-  telemetryClaims?: TelemetryClaims | null;
-  telemetrySessionId?: string;
-  telemetryCompanyUid?: string;
-  changedCount?: number;
-}
-
-export interface ReindexResult {
-  /** 0 = success; 1 = invalid repo root (mirrors the old script's exit codes). */
-  status: number;
-}
-
-// --- small fs helpers (each mirrors a bash test operator) -------------------
-
-/** `[ -d "$p" ]` — exists and is a directory (follows symlinks). */
-function isDir(p: string): boolean {
-  try {
-    return fs.statSync(p).isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-/** `[ -f "$p" ]` — exists and is a regular file (follows symlinks). */
-function isFile(p: string): boolean {
-  try {
-    return fs.statSync(p).isFile();
-  } catch {
-    return false;
-  }
-}
-
-/** `[ -e "$p" ]` — exists, dereferencing symlinks (a broken symlink is false). */
-function existsFollow(p: string): boolean {
-  try {
-    fs.statSync(p);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/** `[ -x "$p" ]` — exists and is executable. */
-function isExecutable(p: string): boolean {
-  try {
-    fs.accessSync(p, fs.constants.X_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/** lstat without throwing (null when the path doesn't exist). */
-function lstatOrNull(p: string): fs.Stats | null {
-  try {
-    return fs.lstatSync(p);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Entries of `dir` matching a bash `dir/*` glob: dotfiles excluded (no
- * dotglob), sorted lexicographically (bash glob order). Missing dir → [].
- */
-function globEntries(dir: string): string[] {
-  let names: string[];
-  try {
-    names = fs.readdirSync(dir);
-  } catch {
-    return [];
-  }
-  return names.filter((n) => !n.startsWith(".")).sort();
-}
-
-function warn(msg: string): void {
-  process.stderr.write(`${msg}\n`);
-}
-
-// Create a directory (recursively), tolerating platform-specific mkdir
-// failures instead of aborting the whole reindex. The classic case (HQ-B0) is
-// a `<ns>:<skill>` wrapper whose ':' is a reserved drive/ADS separator on
-// Windows, where mkdirSync throws ENOENT — but any single mkdir failure (a
-// stray file in the slot, a permission hiccup) should degrade gracefully and
-// let the rest of the reindex proceed. Returns true on success; on failure it
-// logs a clear, actionable warning and returns false so the caller can skip
-// just that piece. PR #98 guarded only the wrapper mkdir; this guards every
-// mkdir site so no single one can crash `hq reindex`.
-function safeMkdir(dir: string, label: string): boolean {
-  try {
-    fs.mkdirSync(dir, { recursive: true });
-    return true;
-  } catch (err) {
-    const code = (err as NodeJS.ErrnoException).code;
-    warn(
-      `reindex: could not create ${label} '${dir}' ` +
-        `(${code ?? "error"}: ${(err as Error).message}); skipping. On Windows ` +
-        `this is usually an illegal path character (e.g. a ':' in a '<ns>:<skill>' ` +
-        `wrapper name).`,
-    );
-    return false;
-  }
-}
-
-// Bridge a source entry into a wrapper, tolerating platform-specific failures
-// instead of aborting the whole reindex — the bridging sibling of safeMkdir.
-// A symlink is preferred: it is nearly free and keeps the wrapper in lock-step
-// with edits to the source. The classic failure (HQ-CLI-4) is Windows WITHOUT
-// Developer Mode (or an elevated shell), where symlink creation is a privileged
-// operation and `fs.symlinkSync` throws EPERM (Win32 ERROR_PRIVILEGE_NOT_HELD).
-//
-// Historically we just skipped that entry, which on Windows left the wrapper
-// directory EMPTY — so the bridged skill/command never surfaced as a slash
-// command at all (bridging silently never worked on such machines). Instead of
-// skipping, fall back to an NTFS hardlink (unprivileged on the same volume, and
-// still inode-shared with the source) and then, only if that also fails, to a
-// plain copy. That is exactly the manual `New-Item -ItemType HardLink` workaround
-// users resort to, made automatic.
-//
-// `absSource` is the real (absolute) path of the source entry — needed because a
-// hardlink/copy references the source directly, not via the relative symlink
-// target. reindex is idempotent and re-run on hooks, so a wrapper left empty by
-// an older build self-heals on the next run: the missing entry is (re)bridged
-// here. On a machine that later gains symlink privilege, an entry already bridged
-// as a hardlink/copy is left in place (the caller treats a non-symlink as
-// pre-existing) — it still works, just isn't upgraded to a symlink. Returns true
-// if the entry was bridged by any method, false only if all of them failed.
-function safeBridgeLink(
-  relativeTarget: string,
-  linkPath: string,
-  absSource: string,
-  label: string,
-): boolean {
-  try {
-    fs.symlinkSync(relativeTarget, linkPath);
-    return true;
-  } catch (symlinkErr) {
-    const symlinkCode = (symlinkErr as NodeJS.ErrnoException).code;
-    // Fallback 1: hardlink. Unprivileged on Windows/NTFS and stays inode-shared
-    // with the source, so in-place edits still propagate. Files only — hardlinking
-    // a directory fails, so a directory entry falls through to the copy below.
-    try {
-      fs.linkSync(absSource, linkPath);
-      return true;
-    } catch {
-      /* not supported here (e.g. directory, cross-volume) — try a copy */
-    }
-    // Fallback 2: plain copy (handles files and directories). A point-in-time
-    // snapshot — the last resort when neither a symlink nor a hardlink is possible.
-    try {
-      fs.cpSync(absSource, linkPath, { recursive: true, force: true });
-      return true;
-    } catch (copyErr) {
-      const copyCode = (copyErr as NodeJS.ErrnoException).code;
-      warn(
-        `reindex: could not bridge ${label} '${linkPath}' -> '${relativeTarget}' ` +
-          `(symlink ${symlinkCode ?? "error"}: ${(symlinkErr as Error).message}; ` +
-          `copy ${copyCode ?? "error"}: ${(copyErr as Error).message}); skipping. ` +
-          `On Windows, creating symlinks needs Developer Mode (Settings -> Privacy ` +
-          `& security -> For developers) or an elevated shell.`,
-      );
-      return false;
-    }
-  }
-}
-
-// Capture the raw session transcripts of every supported coding harness for
-// this HQ tree into `workspace/.session-logs/<harness>/`, so they live inside
-// the HQ tree (where sync/search can see them) on each reindex.
-//
-// Scope — "this HQ tree" = the HQ root cwd OR any working directory UNDER it
-// (worktrees, repo subdirs). Harnesses key their logs by cwd differently, so
-// each helper re-derives the same scope in its own encoding.
-//
-// Contract (per the feature request), applied by every helper:
-//   - copies ALL matching files/folders into `.session-logs/<harness>/…`,
-//   - OVERWRITES existing dest files, and
-//   - NEVER deletes dest entries that lack a source counterpart — a one-way
-//     overlay, not a mirror, so anything already parked in `.session-logs`
-//     survives even after a harness rotates or prunes its own store.
-//
-// Best-effort throughout: any failure warns to stderr and is swallowed so it
-// can never fail the reindex. Each harness is independent — one failing must
-// not stop the others. Home dirs honor CLAUDE_CONFIG_DIR / CODEX_HOME /
-// GROK_HOME, else ~/.claude, ~/.codex, ~/.grok.
-function copySessionLogs(root: string): void {
-  const destBase = path.join(root, "workspace", ".session-logs");
-  for (const capture of [
-    copyClaudeSessionLogs,
-    copyCodexSessionLogs,
-    copyGrokSessionLogs,
-  ]) {
-    try {
-      capture(root, destBase);
-    } catch (err) {
-      warn(`reindex: session-log capture step failed (${(err as Error).message}); skipping.`);
-    }
-  }
-}
-
-// Candidate spellings of the HQ root to match harness-recorded cwds against:
-// the lexical root AND its realpath. Harnesses key logs by the cwd the user
-// actually ran in, which may reach the same tree through a symlink or a
-// case-different spelling (macOS volumes are case-insensitive); realpath
-// canonicalizes both. Best-effort: realpath may throw if root is gone.
-// De-duplicated, lexical root first (stable, preferred dest naming).
-function hqRootCandidates(root: string): string[] {
-  const out = [root];
-  try {
-    const real = fs.realpathSync.native(root);
-    if (real && real !== root) out.push(real);
-  } catch {
-    // best-effort — a missing/unreadable root just means no realpath candidate
-  }
-  return out;
-}
-
-/** `fs.statSync` without throwing (follows symlinks; null when missing). */
-function statOrNull(p: string): fs.Stats | null {
-  try {
-    return fs.statSync(p);
-  } catch {
-    return null;
-  }
-}
-
-// Overlay-copy a whole directory tree: mkdir dest, then recursive+force cpSync
-// (overwrite existing, never prune dest-only entries). Best-effort — warns and
-// returns on any failure. Shared by the Claude + Grok per-cwd-folder captures.
-function copyTreeOverlay(src: string, dest: string, label: string): void {
-  if (!safeMkdir(dest, `${label} directory`)) return;
-  try {
-    fs.cpSync(src, dest, { recursive: true, force: true });
-  } catch (err) {
-    warn(
-      `reindex: could not copy ${label} from '${src}' to '${dest}' ` +
-        `(${(err as NodeJS.ErrnoException).code ?? "error"}: ${(err as Error).message}); skipping.`,
-    );
-  }
-}
-
-// Claude Code: `<claude-config>/projects/<encoded-cwd>/…`, where the cwd is
-// encoded by replacing every non-alphanumeric char with '-'. Because that map
-// is per-character, a descendant cwd's dir name is exactly the root's encoded
-// name + '-' + <encoded-subpath> — so "this HQ tree" is the exact-root dir OR
-// any dir whose name starts with `<slug>-`. Copy each into `.session-logs/claude/`.
-function copyClaudeSessionLogs(root: string, destBase: string): void {
-  const configDir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
-  const projectsDir = path.join(configDir, "projects");
-  if (!isDir(projectsDir)) return;
-
-  const slugs = [...new Set(hqRootCandidates(root).map((r) => r.replace(/[^a-zA-Z0-9]/g, "-")))];
-  for (const entry of globEntries(projectsDir)) {
-    if (!slugs.some((slug) => entry === slug || entry.startsWith(`${slug}-`))) continue;
-    const src = path.join(projectsDir, entry);
-    if (!isDir(src)) continue;
-    copyTreeOverlay(src, path.join(destBase, "claude", entry), "claude session logs");
-  }
-}
-
-// Grok: `<grok-home>/sessions/<url-encoded-cwd>/<session-uuid>/…`, where the cwd
-// is URL-encoded (encodeURIComponent: '/' -> '%2F'). A descendant cwd's key is
-// the root's key + '%2F' + <encoded-subpath>, so match the exact-root key OR
-// that prefix. Copy each matching cwd folder into `.session-logs/grok/`.
-function copyGrokSessionLogs(root: string, destBase: string): void {
-  const grokHome = process.env.GROK_HOME || path.join(os.homedir(), ".grok");
-  const sessionsDir = path.join(grokHome, "sessions");
-  if (!isDir(sessionsDir)) return;
-
-  const keys = [...new Set(hqRootCandidates(root).map((r) => encodeURIComponent(r)))];
-  for (const entry of globEntries(sessionsDir)) {
-    if (!keys.some((key) => entry === key || entry.startsWith(`${key}%2F`))) continue;
-    const src = path.join(sessionsDir, entry);
-    if (!isDir(src)) continue;
-    copyTreeOverlay(src, path.join(destBase, "grok", entry), "grok session logs");
-  }
-}
-
-// Codex: `<codex-home>/sessions/YYYY/MM/DD/rollout-*.jsonl` — a DATE tree, not
-// per-project. The working dir is only recorded inside each rollout's first
-// line (`session_meta`, at `payload.cwd`). Walk the tree and capture a rollout
-// iff its recorded cwd is the HQ root or under it, mirroring the date-relative
-// path under `.session-logs/codex/`. A rollout already copied and unchanged is
-// skipped by mtime, so a steady-state reindex only classifies newly-written
-// rollouts — the full-tree cwd scan is a one-time first-run cost.
-function copyCodexSessionLogs(root: string, destBase: string): void {
-  const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
-  const sessionsDir = path.join(codexHome, "sessions");
-  if (!isDir(sessionsDir)) return;
-
-  const destDir = path.join(destBase, "codex");
-  const candidates = hqRootCandidates(root);
-  const prefixes = candidates.map((r) => (r.endsWith(path.sep) ? r : r + path.sep));
-
-  for (const abs of walkFiles(sessionsDir)) {
-    if (!abs.endsWith(".jsonl")) continue;
-    const srcStat = statOrNull(abs);
-    if (!srcStat) continue;
-
-    const dest = path.join(destDir, path.relative(sessionsDir, abs));
-    // Cheap skip: already captured and unchanged since (dest mtime is the copy
-    // time, so it stays >= src mtime until the rollout is appended to again).
-    const destStat = statOrNull(dest);
-    if (destStat && destStat.mtimeMs >= srcStat.mtimeMs) continue;
-
-    const cwd = readCodexRolloutCwd(abs);
-    if (cwd === null) continue;
-    if (!candidates.includes(cwd) && !prefixes.some((prefix) => cwd.startsWith(prefix))) continue;
-
-    if (!safeMkdir(path.dirname(dest), "codex session-log dir")) continue;
-    try {
-      fs.copyFileSync(abs, dest);
-    } catch (err) {
-      warn(
-        `reindex: could not copy codex session log '${abs}' -> '${dest}' ` +
-          `(${(err as NodeJS.ErrnoException).code ?? "error"}: ${(err as Error).message}); skipping.`,
-      );
-    }
-  }
-}
-
-// Collect every regular file under `dir` (absolute paths) in depth-first order.
-// Symlinks are not followed (lstat gate) so a stray link can't escape the tree
-// or loop. Missing/unreadable dirs yield []. Best-effort — mirrors
-// globEntries' tolerance.
-function walkFiles(dir: string): string[] {
-  const out: string[] = [];
-  const stack: Array<{ names: string[]; index: number; dir: string }> = [];
-  const enterDirectory = (currentDir: string): void => {
-    try {
-      stack.push({ names: fs.readdirSync(currentDir), index: 0, dir: currentDir });
-    } catch {
-      // Missing and unreadable children are ignored just like the recursive
-      // walker did when its nested call returned an empty list.
-    }
-  };
-
-  enterDirectory(dir);
-  while (stack.length > 0) {
-    const frame = stack[stack.length - 1];
-    if (frame.index >= frame.names.length) {
-      stack.pop();
-      continue;
-    }
-    const name = frame.names[frame.index++];
-    const abs = path.join(frame.dir, name);
-    const st = lstatOrNull(abs);
-    if (!st) continue;
-    if (st.isDirectory()) enterDirectory(abs);
-    else if (st.isFile()) out.push(abs);
-  }
-  return out;
-}
-
-// Extract `payload.cwd` (Codex ≥ the session_meta format; falls back to a
-// top-level `cwd`) from a rollout's first line, reading only that line. Codex
-// records cwd early, before the large `base_instructions` blob, but the line
-// can still be tens of KB — so read up to a generous cap and stop at the first
-// newline. Returns null on any parse/read failure (the rollout is then skipped).
-function readCodexRolloutCwd(file: string): string | null {
-  const line = readFirstLine(file, 4 * 1024 * 1024);
-  if (line === null) return null;
-  try {
-    const obj = JSON.parse(line) as { cwd?: unknown; payload?: { cwd?: unknown } };
-    const cwd = obj?.payload?.cwd ?? obj?.cwd;
-    return typeof cwd === "string" ? cwd : null;
-  } catch {
-    return null;
-  }
-}
-
-// Read the first line of `file` (up to `capBytes`), returning it WITHOUT the
-// trailing newline, or null on error / empty. Byte-accumulates and decodes once
-// so a multibyte char split across a read boundary can't corrupt the result.
-function readFirstLine(file: string, capBytes: number): string | null {
-  let fd: number | null = null;
-  try {
-    fd = fs.openSync(file, "r");
-    const chunks: Buffer[] = [];
-    const chunk = Buffer.allocUnsafe(65536);
-    let total = 0;
-    while (total < capBytes) {
-      const n = fs.readSync(fd, chunk, 0, chunk.length, total);
-      if (n <= 0) break;
-      const nl = chunk.indexOf(0x0a, 0);
-      if (nl !== -1 && nl < n) {
-        chunks.push(Buffer.from(chunk.subarray(0, nl)));
-        return Buffer.concat(chunks).toString("utf8");
-      }
-      chunks.push(Buffer.from(chunk.subarray(0, n)));
-      total += n;
-    }
-    return chunks.length ? Buffer.concat(chunks).toString("utf8") : null;
-  } catch {
-    return null;
-  } finally {
-    if (fd !== null) {
-      try {
-        fs.closeSync(fd);
-      } catch {
-        /* best-effort */
-      }
-    }
-  }
-}
-
-// --- legacy `.claude/commands/<ns>/<skill>.md` symlink matcher --------------
-// Mirrors the bash `case` patterns; `*` matches any chars (including `/`).
-function isLegacyCommandTarget(t: string): boolean {
-  return (
-    /^\.\.\/\.\.\/\.\.\/companies\/.*\/skills\/.*\/SKILL\.md$/.test(t) ||
-    /^\.\.\/\.\.\/\.\.\/core\/skills\/.*\/SKILL\.md$/.test(t) ||
-    /^\.\.\/\.\.\/\.\.\/personal\/skills\/.*\/SKILL\.md$/.test(t) ||
-    /^\.\.\/\.\.\/\.\.\/core\/packages\/.*\/skills\/.*\/SKILL\.md$/.test(t)
-  );
-}
-
-/**
- * Run reindex against an HQ root. Synchronous — the work is cheap and
- * idempotent, and callers (the hook shim, sync/rescue, tests) want the exit
- * status. Diagnostics are written to stderr so the caller's stdout stays clean
- * (hooks must not emit stdout that the agent interprets).
- */
-export function reindex(opts: ReindexOptions = {}): ReindexResult {
-  const rawRoot = opts.repoRoot ?? process.cwd();
-  if (!isDir(rawRoot)) {
-    warn(`reindex: REPO_ROOT '${rawRoot}' is not a directory`);
-    const result = { status: 1 };
-    emitReindexTelemetry(opts, result, "not_attempted");
-    return result;
-  }
-  const root = path.resolve(rawRoot);
-
-  // Acquire the per-root "reindex"-scope lock unless an internal caller
-  // (sync/rescue) opted out. This scope is SEPARATE from sync/rescue's
-  // "operation" lock, so a long-lived watch-mode sync-runner holding the
-  // operation lock never starves us (feedback_ed98d810) — we only contend with
-  // other reindexes. A live holder → refuse fast with the holder's command +
-  // PID. The whole body runs inside the try so the lock is released on every
-  // exit path (the process-level signal/exit hooks are the crash backstop).
-  let opLock: LockHandle | null = null;
-  if (!opts.skipLock) {
-    try {
-      opLock = acquireOperationLock(root, "reindex", {
-        scope: "reindex",
-        timeoutSec: opts.lockTimeoutSec,
-      });
-    } catch (err) {
-      if (err instanceof OperationLockedError) {
-        warn(err.message);
-        const result = { status: OPERATION_LOCKED_EXIT };
-        emitReindexTelemetry(opts, result, "locked");
-        return result;
-      }
-      if (err instanceof OperationLockUnwritableError) {
-        // The lock dir isn't writable (e.g. macOS EPERM / Linux EACCES on a
-        // root-owned or restricted ~/.hq). This is an environmental problem on
-        // the user's machine, not an HQ fault — surface the actionable guidance
-        // and exit cleanly instead of crashing with a raw `EPERM ... open`
-        // (HQ-CLI-2).
-        warn(err.message);
-        const result = { status: OPERATION_LOCK_UNWRITABLE_EXIT };
-        emitReindexTelemetry(opts, result, "unwritable");
-        return result;
-      }
-      throw err;
-    }
-  }
-  try {
-
-  // --- Legacy knowledge-repo materialization --------------------------------
-  // Knowledge repositories must be real directories at their canonical paths
-  // (policy knowledge-repositories-never-symlink); a symlink to a repo under
-  // repos/ syncs as an empty vault marker. Scour the canonical knowledge
-  // locations, pull + copy each legacy repo inline, and drop the fully
-  // migrated legacy repo. Best-effort and a pure no-op on compliant trees.
-  materializeLegacyKnowledgeRepos(root);
-
-  // Overlay/skill-wrapper mirroring is best-effort and, on a normal synced HQ,
-  // legitimately no-ops for MANY entries (a real core file already sits where a
-  // symlink would go, or a link already points elsewhere). Emitting one stderr
-  // line PER such entry floods the runner's Sentry breadcrumb ring (100 entries)
-  // and evicts the real per-company sync error, making code-2 syncs impossible to
-  // triage (HQ-SYNC-2 / HQ-SYNC-WEB-6). Collapse those per-file lines into a
-  // single end-of-run summary; keep per-file detail behind HQ_REINDEX_VERBOSE=1.
-  const verbose = process.env.HQ_REINDEX_VERBOSE === "1";
-  let skippedNonSymlink = 0;
-  let skippedPointsElsewhere = 0;
-
-  // Best-effort: each wrapper mkdir below is recursive and re-creates this
-  // parent as needed, so a failure here is non-fatal — warn and carry on so
-  // personal-overlay mirroring and registry regeneration still run.
-  safeMkdir(path.join(root, ".claude", "skills"), ".claude/skills directory");
-
-  // --- Build (namespace, src_rel) pairs -------------------------------------
-  const pairs: { ns: string; srcRel: string }[] = [];
-  const addNs = (ns: string, srcRel: string): void => {
-    if (isDir(path.join(root, srcRel))) pairs.push({ ns, srcRel });
-  };
-
-  for (const slug of globEntries(path.join(root, "companies"))) {
-    if (isDir(path.join(root, "companies", slug))) {
-      addNs(slug, `companies/${slug}/skills`);
-    }
-  }
-  addNs("core", "core/skills");
-  addNs("personal", "personal/skills");
-  for (const pack of globEntries(path.join(root, "core", "packages"))) {
-    if (isDir(path.join(root, "core", "packages", pack))) {
-      addNs(pack, `core/packages/${pack}/skills`);
-    }
-  }
-
-  // --- 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)) {
-    for (const nsName of globEntries(commandsDir)) {
-      const cmdNsDir = path.join(commandsDir, nsName);
-      // Only real directories (bash `*/`); folder-level symlinks are left for
-      // a human to resolve. lstat().isDirectory() is false for a symlink, so
-      // this single check covers both bash guards.
-      const st = lstatOrNull(cmdNsDir);
-      if (!st || !st.isDirectory()) continue;
-
-      for (const f of globEntries(cmdNsDir)) {
-        if (!f.endsWith(".md")) continue;
-        const fp = path.join(cmdNsDir, f);
-        const fst = lstatOrNull(fp);
-        if (!fst || !fst.isSymbolicLink()) continue;
-        const target = readlinkOrNull(fp);
-        if (target && isLegacyCommandTarget(target)) {
-          try {
-            fs.rmSync(fp);
-          } catch {
-            /* best-effort */
-          }
-        }
-      }
-
-      // rmdir if empty; ignore "directory not empty".
-      try {
-        fs.rmdirSync(cmdNsDir);
-      } catch {
-        /* not empty / gone — fine */
-      }
-    }
-  }
-
-  // --- Skill wrapper creation -----------------------------------------------
-  const expectedWrappers = new Set<string>();
-  const seen = new Set<string>();
-
-  for (const { ns, srcRel } of pairs) {
-    // First writer for a namespace wins.
-    if (seen.has(ns)) {
-      warn(
-        `reindex: namespace '${ns}' already claimed by an earlier source; skipping ${srcRel}`,
-      );
-      continue;
-    }
-    seen.add(ns);
-
-    const srcAbs = path.join(root, srcRel);
-    for (const skillName of globEntries(srcAbs)) {
-      const skillPath = path.join(srcAbs, skillName);
-      if (!isDir(skillPath)) continue;
-      // Skip `_shared`, `_template`, etc. (dotfiles already excluded by glob).
-      if (skillName.startsWith("_")) continue;
-      if (!isFile(path.join(skillPath, "SKILL.md"))) continue;
-
-      const wrapperName = encodeLocalVaultSegment(`${ns}:${skillName}`);
-      const wrapper = path.join(root, ".claude", "skills", wrapperName);
-      expectedWrappers.add(wrapperName);
-
-      const wst = lstatOrNull(wrapper);
-      // If something non-directory, non-symlink occupies the slot, bail.
-      if (wst && !wst.isSymbolicLink() && !wst.isDirectory()) {
-        warn(`reindex: ${wrapper} exists and is not a directory; skipping`);
-        continue;
-      }
-      // If it's a symlink (legacy directory-symlink form), replace it with a
-      // real directory of per-file symlinks.
-      if (wst && wst.isSymbolicLink()) {
-        try {
-          fs.rmSync(wrapper);
-        } catch {
-          /* best-effort */
-        }
-      }
-      // Namespaced wrappers embed a ':' in the directory name (`<ns>:<skill>`),
-      // which is a reserved drive/ADS separator on Windows where mkdir fails
-      // with ENOENT (HQ-B0). Skip just this wrapper instead of aborting the
-      // whole reindex; the skill's source folder is untouched.
-      if (!safeMkdir(wrapper, `skill wrapper '${wrapperName}'`)) continue;
-
-      // Symlink every (non-hidden) entry in the source skill folder. The
-      // wrapper lives three levels below REPO_ROOT.
-      for (const entry of globEntries(skillPath)) {
-        const entryPath = path.join(skillPath, entry);
-        if (!existsFollow(entryPath)) continue;
-        const linkPath = path.join(wrapper, entry);
-        const relativeTarget = `../../../${srcRel}/${skillName}/${entry}`;
-
-        const lst = lstatOrNull(linkPath);
-        if (lst && lst.isSymbolicLink()) {
-          const current = readlinkOrNull(linkPath);
-          if (current === relativeTarget) continue;
-          skippedPointsElsewhere++;
-          if (verbose) {
-            warn(
-              `reindex: .claude/skills/${wrapperName}/${entry} 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;
-        }
-
-        safeBridgeLink(relativeTarget, linkPath, entryPath, `.claude/skills/${wrapperName}/${entry}`);
-      }
-
-      // Prune symlinks in the wrapper whose source entry no longer exists.
-      for (const entry of globEntries(wrapper)) {
-        const linkPath = path.join(wrapper, entry);
-        const lst = lstatOrNull(linkPath);
-        if (!lst || !lst.isSymbolicLink()) continue;
-        if (existsFollow(linkPath)) continue;
-        try {
-          fs.rmSync(linkPath);
-        } catch {
-          /* best-effort */
-        }
-      }
-    }
-  }
-
-  // --- Cleanup pass B: drop orphan <ns>:<skill> wrappers --------------------
-  const skillsDir = path.join(root, ".claude", "skills");
-  for (const entry of globEntries(skillsDir)) {
-    const entryPath = path.join(skillsDir, entry);
-    const lst = lstatOrNull(entryPath);
-    if (!lst) continue; // accept broken symlinks (lstat still succeeds)
-    const canonicalEntry = decodeLocalVaultSegment(entry);
-    if (!canonicalEntry.includes(":")) continue; // not a namespaced wrapper
-    if (expectedWrappers.has(entry)) continue; // maintained this run
-
-    // A wrapper is "managed" only when its namespace prefix matches the
-    // namespace encoded in its symlink target — this distinguishes
-    // script-produced wrappers from hand-authored composite wrappers.
-    const ns = canonicalEntry.slice(0, canonicalEntry.indexOf(":"));
-    const matchTarget = (t: string | null, p: string): boolean => {
-      if (!t) return false;
-      if (t.startsWith(`${p}/personal/skills/`)) return ns === "personal";
-      if (t.startsWith(`${p}/core/skills/`)) return ns === "core";
-      if (t.startsWith(`${p}/companies/${ns}/skills/`)) return true;
-      if (t.startsWith(`${p}/core/packages/${ns}/skills/`)) return true;
-      return false;
-    };
-
-    let isManaged = false;
-    if (lst.isSymbolicLink()) {
-      // (a) directory-style symlink wrapper (older shape): 2-level target.
-      isManaged = matchTarget(readlinkOrNull(entryPath), "../..");
-    } else if (lst.isDirectory()) {
-      // (b) real directory of per-file symlinks (current shape): 3-level.
-      for (const f of globEntries(entryPath)) {
-        const fp = path.join(entryPath, f);
-        const fst = lstatOrNull(fp);
-        if (!fst || !fst.isSymbolicLink()) continue;
-        if (matchTarget(readlinkOrNull(fp), "../../..")) {
-          isManaged = true;
-          break;
-        }
-      }
-    }
-    if (!isManaged) continue;
-
-    // Managed-namespace wrapper with no corresponding live source → drop.
-    try {
-      if (lst.isSymbolicLink()) {
-        fs.rmSync(entryPath);
-      } else if (lst.isDirectory()) {
-        fs.rmSync(entryPath, { recursive: true, force: true });
-      }
-    } catch {
-      /* best-effort */
-    }
-  }
-
-  // --- 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;
-      }
-
-      safeBridgeLink(relativeTarget, linkPath, path.join(srcAbs, entry), `.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
-  // workers-registry generator walks personal/workers, qmd-reindex-after-sync
-  // registers a personal/knowledge collection, and repo-run-registry reads
-  // personal/settings/orchestrator.yaml). personal is the SOLE read source for
-  // the personal overlay, so reindex no longer SYMLINKS personal/<type>/<entry>
-  // into core/<type>/<entry> — a mirror would now double-surface every entry
-  // (read once directly, once via the link).
-  //
-  // Migration cleanup: prune any mirror symlink a PRIOR release created —
-  // core/<type>/<entry> whose target is EXACTLY `../../personal/<type>/<entry>`.
-  // That exact-target discriminator (policy wrapper-sync-orphan-cleanup-cross-
-  // check) means a real release-shipped core file (not a symlink) or a human-
-  // authored symlink pointing elsewhere is never touched. Unlike the old
-  // "Cleanup pass C", this prunes the link WHETHER OR NOT its personal source
-  // still exists: the mirror is retired, so every managed link is now stale.
-  // Kept for a few releases so existing trees self-heal on the next reindex.
-  for (const type of ["knowledge", "policies", "workers", "settings"]) {
-    const coreDir = path.join(root, "core", type);
-    for (const entry of globEntries(coreDir)) {
-      const linkPath = path.join(coreDir, entry);
-      const lst = lstatOrNull(linkPath);
-      if (!lst || !lst.isSymbolicLink()) continue; // real file/dir → not ours
-      if (readlinkOrNull(linkPath) !== `../../personal/${type}/${entry}`) continue; // not a managed mirror link
-      // Managed mirror symlink from a prior release → prune (mirror is retired).
-      try {
-        fs.rmSync(linkPath);
-      } catch {
-        /* best-effort */
-      }
-    }
-  }
-
-  // --- Session-log capture --------------------------------------------------
-  // Overlay this root's Claude Code session logs into workspace/.session-logs
-  // (copy-all, overwrite, never-prune). Best-effort; never fails the reindex.
-  copySessionLogs(root);
-
-  // --- Workers registry regeneration ----------------------------------------
-  // Source of truth: each worker.yaml. The registry is a derived index — the
-  // generator (when present in the operated-on tree) keeps it in sync.
-  // Best-effort and idempotent; never fails the reindex.
-  const genScript = path.join(root, "core", "scripts", "generate-workers-registry.sh");
-  if (isExecutable(genScript)) {
-    // Route the generator's stdout+stderr to our stderr (`>&2 2>&1`).
-    spawnSync("bash", [genScript], { stdio: ["ignore", 2, 2] });
-  }
-
-  // One-line summary in place of the per-file overlay-skip spam (see the comment
-  // at the top of the try). Only emitted when something was skipped, so a clean
-  // run stays silent and the breadcrumb ring is free for real sync errors.
-  if (skippedNonSymlink > 0 || skippedPointsElsewhere > 0) {
-    const parts: string[] = [];
-    if (skippedNonSymlink > 0) {
-      parts.push(`${skippedNonSymlink} pre-existing non-symlink ${skippedNonSymlink === 1 ? "entry" : "entries"}`);
-    }
-    if (skippedPointsElsewhere > 0) {
-      parts.push(`${skippedPointsElsewhere} ${skippedPointsElsewhere === 1 ? "entry" : "entries"} already pointing elsewhere`);
-    }
-    warn(
-      `reindex: left ${parts.join(" + ")} untouched (overlay mirror is best-effort; set HQ_REINDEX_VERBOSE=1 for per-file detail)`,
-    );
-  }
-
-  const result = { status: 0 };
-  emitReindexTelemetry(opts, result, opts.skipLock ? "skipped" : "acquired");
-  return result;
-  } finally {
-    opLock?.release();
-  }
-}
-
-function emitReindexTelemetry(
-  opts: ReindexOptions,
-  result: ReindexResult,
-  lockResult: string,
-): void {
-  void emitCloudTelemetry(
-    opts.telemetryClient,
-    {
-      eventName: "reindex_run",
-      source: "hq-reindex",
-      ...(opts.telemetryCompanyUid ? { companyUid: opts.telemetryCompanyUid } : {}),
-      ...(opts.telemetrySessionId ? { sessionId: opts.telemetrySessionId } : {}),
-      properties: {
-        result: result.status === 0 ? "completed" : "failed",
-        statusCode: result.status,
-        lockResult,
-        changedCount: opts.changedCount ?? 0,
-        skipLockState: opts.skipLock === true ? "skipped" : "acquired",
-      },
-    },
-    { claims: opts.telemetryClaims },
-  );
-}