@indigoai-us/hq-cli 5.77.6 → 5.77.8

package/src/commands/group-grants.ts

@@ -189,15 +189,18 @@ export async function revokeGroupGrant(
 export async function listOutboundGrants(
   token: string,
   sourceCompanyUid: string,
-  groupId?: string,
+  groupId: string,
 ): Promise<GroupGrant[]> {
-  const query: Record<string, string> = { sourceCompanyUid };
-  if (groupId) query.groupId = groupId;
+  if (!GROUP_ID_PATTERN.test(groupId)) {
+    throw new Error(
+      `Invalid group id '${groupId}': must match grp_<alphanumeric, underscore, hyphen>`,
+    );
+  }
 
   const res = await vaultApiFetch({
     token,
     path: "/group-grants/outbound",
-    query,
+    query: { sourceCompanyUid, groupId },
   });
 
   if (!res.ok) {
@@ -385,13 +388,13 @@ export function registerGroupGrantsCommand(program: Command): void {
   grants
     .command("outbound")
     .description(
-      "List grants the source company's groups hold on other companies",
+      "List grants a source-company group holds on other companies",
     )
-    .option(
+    .requiredOption(
       "--group <groupId>",
-      "Filter to a single group id",
+      "Group id to inspect",
     )
-    .action(async (opts: { group?: string }) => {
+    .action(async (opts: { group: string }) => {
       try {
         const token = await ensureCognitoToken();
         const sourceSlug = grants.opts().company as string | undefined;

package/src/commands/integrations.test.ts

@@ -513,3 +513,121 @@ describe("integration gateway 401 → AuthError (HQ-CLI-9)", () => {
     expect((err as Error).message).toMatch(/monday rejected the board id/);
   });
 });
+
+// HQ-CLI-B: `hq integrations tools|call … --provider …` against a connection the
+// caller has NOT been granted returned HTTP 200 with a JSON-RPC error
+// { code: -32003, message: "You do not have access to this integration. Ask its
+// owner to share it with you.", data: { code: "IntegrationAccessDenied" } }.
+// `callGateway` threw an IntegrationsCliError WITHOUT `expected`, so it defaulted
+// to `expected === false` and the top-level handler shipped a GOVERNED, correct
+// access denial to Sentry as an error-level fatal — 40 identical, unfixable
+// events for one user. A caller-side JSON-RPC code (UNAUTHORIZED / INVALID_PARAMS)
+// is the analog of a client 4xx and must be printed to the user, not captured;
+// genuine server/provider/protocol faults must still report.
+describe("gateway JSON-RPC error classification (HQ-CLI-B)", () => {
+  function gatewayJsonRpcError(code: number | undefined, message: string, data?: unknown) {
+    return jsonResponse({
+      jsonrpc: "2.0",
+      id: "x",
+      error: { ...(code == null ? {} : { code }), message, ...(data ? { data } : {}) },
+    });
+  }
+
+  async function runGatewayCall(): Promise<unknown> {
+    return runCli([
+      "integrations",
+      "call",
+      "get_board_info",
+      "--provider",
+      "linear",
+      "--args",
+      "{}",
+    ]).then(
+      () => {
+        throw new Error("expected runCli to throw");
+      },
+      (e: unknown) => e,
+    );
+  }
+
+  it("marks the access-denied gateway error (-32003) as expected and preserves its actionable message", async () => {
+    vaultApiFetchMock
+      .mockResolvedValueOnce(connectionsResponse())
+      .mockResolvedValueOnce(
+        gatewayJsonRpcError(
+          -32003,
+          "You do not have access to this integration. Ask its owner to share it with you.",
+          { code: "IntegrationAccessDenied" },
+        ),
+      );
+
+    const err = await runGatewayCall();
+
+    expect(err).toBeInstanceOf(IntegrationsCliError);
+    // The regression: this was `false` and flooded Sentry with a governed denial.
+    expect((err as IntegrationsCliError).expected).toBe(true);
+    // A connection-level denial is NOT an expired session — never an AuthError.
+    expect(isAuthError(err)).toBe(false);
+    expect((err as Error).message).toContain("do not have access to this integration");
+  });
+
+  it("also marks access-denied as expected on the `tools` path (same callGateway seam)", async () => {
+    vaultApiFetchMock
+      .mockResolvedValueOnce(connectionsResponse())
+      .mockResolvedValueOnce(
+        gatewayJsonRpcError(
+          -32003,
+          "You do not have access to this integration. Ask its owner to share it with you.",
+        ),
+      );
+
+    const err = await runCli(["integrations", "tools", "--provider", "linear"]).then(
+      () => {
+        throw new Error("expected runCli to throw");
+      },
+      (e: unknown) => e,
+    );
+
+    expect(err).toBeInstanceOf(IntegrationsCliError);
+    expect((err as IntegrationsCliError).expected).toBe(true);
+  });
+
+  it("marks an invalid-params gateway error (-32602) as expected", async () => {
+    vaultApiFetchMock
+      .mockResolvedValueOnce(connectionsResponse())
+      .mockResolvedValueOnce(gatewayJsonRpcError(-32602, "Unknown integration tool: get_board_info"));
+
+    const err = await runGatewayCall();
+
+    expect(err).toBeInstanceOf(IntegrationsCliError);
+    expect((err as IntegrationsCliError).expected).toBe(true);
+  });
+
+  it("still reports genuine provider/internal/conflict gateway faults (expected === false)", async () => {
+    // -32050 PROVIDER_ERROR, -32603 INTERNAL_ERROR, and -32009 CONFLICT (which the
+    // gateway raises for a confirm queue being unavailable or an owner
+    // notification failing) are real faults that must keep reaching Sentry.
+    for (const code of [-32050, -32603, -32009]) {
+      vaultApiFetchMock
+        .mockResolvedValueOnce(connectionsResponse())
+        .mockResolvedValueOnce(gatewayJsonRpcError(code, "gateway fault"));
+
+      const err = await runGatewayCall();
+
+      expect(err).toBeInstanceOf(IntegrationsCliError);
+      expect((err as IntegrationsCliError).expected).toBe(false);
+      vaultApiFetchMock.mockClear();
+    }
+  });
+
+  it("reports a gateway error with no JSON-RPC code (unclassified → expected === false)", async () => {
+    vaultApiFetchMock
+      .mockResolvedValueOnce(connectionsResponse())
+      .mockResolvedValueOnce(gatewayJsonRpcError(undefined, "codeless failure"));
+
+    const err = await runGatewayCall();
+
+    expect(err).toBeInstanceOf(IntegrationsCliError);
+    expect((err as IntegrationsCliError).expected).toBe(false);
+  });
+});

package/src/commands/integrations.ts

@@ -76,6 +76,31 @@ function isClientError(status: number): boolean {
   return status >= 400 && status < 500;
 }
 
+// The integration gateway answers `POST /v1/integrations/mcp` JSON-RPC-style: a
+// transport failure is a non-2xx HTTP status, but a GOVERNED refusal arrives as
+// HTTP 200 carrying a JSON-RPC `error` object (mirrors hq-pro's
+// integration-mcp/server.ts error mapping). These caller-side codes are the
+// JSON-RPC analog of a client 4xx — the caller's request/state/permission,
+// expected and actionable, not an hq-cli defect — so they are printed to the
+// user and skipped for Sentry capture (HQ-CLI-B):
+//   -32003 UNAUTHORIZED   — connection-level access denial, e.g. the
+//                           "You do not have access to this integration. Ask its
+//                           owner to share it with you." (IntegrationAccessDenied)
+//                           that flooded Sentry, plus ConnectionNotFound / a
+//                           read-only share rejecting a write.
+//   -32602 INVALID_PARAMS — an unknown tool or unsupported provider for the
+//                           connection (a bad request the caller can correct).
+// Everything else stays unexpected so a genuine fault still reaches Sentry:
+// PROVIDER_ERROR (-32050, an upstream provider fault), INTERNAL_ERROR (-32603),
+// CONFLICT (-32009, which the gateway also raises for a confirm queue being
+// unavailable or an owner notification failing — real backend faults worth a
+// report), METHOD_NOT_FOUND / PARSE_ERROR, and any absent or unrecognized code.
+const EXPECTED_GATEWAY_ERROR_CODES = new Set<number>([-32003, -32602]);
+
+function isExpectedGatewayError(code: number | undefined): boolean {
+  return code != null && EXPECTED_GATEWAY_ERROR_CODES.has(code);
+}
+
 // A 401 from ANY integration-gateway vault call means the caller's HQ session
 // is expired or missing — an expected auth state fixed by `hq login`, not an
 // hq-cli defect. Raise the same typed AuthError the vault company-resolution
@@ -196,6 +221,7 @@ export async function callGateway(
   if (message.error) {
     throw new IntegrationsCliError(
       message.error.message ?? "Integration gateway returned an error.",
+      { expected: isExpectedGatewayError(message.error.code) },
     );
   }
   return message;

package/src/commands/reindex.test.ts

@@ -7,17 +7,62 @@ import {
   vi,
   type MockInstance,
 } from "vitest";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
 
-// Mock the hq-cloud reindex() so the command runs without touching the FS.
+// Mock the hq-cloud commands so the command only touches its temporary HQ roots.
 vi.mock("@indigoai-us/hq-cloud", () => ({
   reindex: vi.fn(() => ({ status: 0 })),
+  rescue: vi.fn(() => ({ status: 0 })),
 }));
 
 import { Command } from "commander";
-import { reindex } from "@indigoai-us/hq-cloud";
+import { reindex, rescue } from "@indigoai-us/hq-cloud";
 import { registerReindexCommand } from "./reindex.js";
 
 const reindexMock = reindex as unknown as MockInstance<typeof reindex>;
+const rescueMock = rescue as unknown as MockInstance<typeof rescue>;
+
+const HEALTHY_SETTINGS = {
+  hooks: Object.fromEntries(
+    ["SessionStart", "UserPromptSubmit", "PreToolUse"].map((event) => [
+      event,
+      [{ matcher: "", hooks: [{ type: "command", command: `echo ${event}` }] }],
+    ])
+  ),
+};
+
+let tempRoots: string[] = [];
+let defaultRoot: string;
+
+function writeSettings(root: string, settings: unknown): void {
+  fs.mkdirSync(path.join(root, ".claude"), { recursive: true });
+  fs.writeFileSync(path.join(root, ".claude", "settings.json"), JSON.stringify(settings, null, 2));
+}
+
+function makeHqRoot(settings: unknown = HEALTHY_SETTINGS): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "hq-reindex-"));
+  tempRoots.push(root);
+  fs.mkdirSync(path.join(root, ".claude"), { recursive: true });
+  fs.mkdirSync(path.join(root, "companies"), { recursive: true });
+  fs.mkdirSync(path.join(root, "personal"), { recursive: true });
+  fs.mkdirSync(path.join(root, "core"), { recursive: true });
+  fs.writeFileSync(path.join(root, "core", "core.yaml"), 'version: 1\nhqVersion: "15.0.56"\n');
+  if (settings !== undefined) writeSettings(root, settings);
+  return root;
+}
+
+function restoreShippedHookConfig(options: { hqRoot?: string }): { status: number } {
+  const root = options.hqRoot;
+  if (!root) throw new Error("rescue requires hqRoot");
+  const settings = path.join(root, ".claude", "settings.json");
+  if (fs.existsSync(settings)) {
+    fs.copyFileSync(settings, path.join(root, "personal", "settings.json"));
+  }
+  writeSettings(root, HEALTHY_SETTINGS);
+  return { status: 0 };
+}
 
 function buildProgram(): Command {
   const program = new Command();
@@ -31,9 +76,10 @@ function buildProgram(): Command {
 }
 
 async function run(...args: string[]): Promise<void> {
+  const commandArgs = args.includes("--repo-root") ? args : ["--repo-root", defaultRoot, ...args];
   // process.exit is spied to throw; swallow that so parseAsync resolves.
   try {
-    await buildProgram().parseAsync(["node", "hq", "reindex", ...args]);
+    await buildProgram().parseAsync(["node", "hq", "reindex", ...commandArgs]);
   } catch (err) {
     if (!(err instanceof Error) || !err.message.startsWith("__EXIT__:")) throw err;
   }
@@ -41,18 +87,26 @@ async function run(...args: string[]): Promise<void> {
 
 let exitSpy: MockInstance<typeof process.exit>;
 let savedLockTimeout: string | undefined;
+let logSpy: MockInstance<typeof console.log>;
+let warnSpy: MockInstance<typeof console.warn>;
 
 beforeEach(() => {
   vi.clearAllMocks();
   savedLockTimeout = process.env.HQ_OP_LOCK_TIMEOUT;
   delete process.env.HQ_OP_LOCK_TIMEOUT;
+  tempRoots = [];
+  defaultRoot = makeHqRoot();
+  rescueMock.mockImplementation(restoreShippedHookConfig as never);
   exitSpy = vi.spyOn(process, "exit").mockImplementation(((code?: number) => {
     throw new Error(`__EXIT__:${code ?? 0}`);
   }) as never);
+  logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+  warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined);
 });
 
 afterEach(() => {
   vi.restoreAllMocks();
+  for (const root of tempRoots) fs.rmSync(root, { recursive: true, force: true });
   if (savedLockTimeout === undefined) delete process.env.HQ_OP_LOCK_TIMEOUT;
   else process.env.HQ_OP_LOCK_TIMEOUT = savedLockTimeout;
 });
@@ -92,3 +146,114 @@ describe("hq reindex lock-wait policy", () => {
     expect(process.env.HQ_OP_LOCK_TIMEOUT).toBeUndefined();
   });
 });
+
+describe("hq reindex hook health", () => {
+  it("does not warn when all lifecycle hooks are declared", async () => {
+    await run();
+
+    expect(rescueMock).not.toHaveBeenCalled();
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("leaves a healthy root alone across repeated reindexes", async () => {
+    const root = makeHqRoot();
+
+    await run("--repo-root", root);
+    await run("--repo-root", root);
+
+    expect(rescueMock).not.toHaveBeenCalled();
+    expect(warnSpy).not.toHaveBeenCalled();
+    expect(logSpy).not.toHaveBeenCalledWith("reindex: repaired HQ hook config");
+    expect(reindexMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("warns and repairs missing settings.json non-interactively", async () => {
+    const root = makeHqRoot();
+    fs.rmSync(path.join(root, ".claude", "settings.json"));
+
+    await run("--repo-root", root);
+
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining(".claude/settings.json is missing"));
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("hq rescue -y --paths .claude"));
+    expect(rescueMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        hqRoot: root,
+        source: "indigoai-us/hq-core",
+        ref: "v15.0.56",
+        paths: [".claude"],
+        assumeYes: true,
+      })
+    );
+    expect(JSON.parse(fs.readFileSync(path.join(root, ".claude", "settings.json"), "utf8"))).toEqual(
+      HEALTHY_SETTINGS
+    );
+    expect(logSpy).toHaveBeenCalledWith("reindex: repaired HQ hook config");
+    expect(exitSpy).toHaveBeenCalledWith(0);
+  });
+
+  it("warns and repairs settings.json when it declares none of the lifecycle hooks", async () => {
+    const root = makeHqRoot({ hooks: { Stop: [{ hooks: [{ type: "command", command: "echo stop" }] }] } });
+
+    await run("--repo-root", root);
+
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("no SessionStart, UserPromptSubmit, or PreToolUse command hook"));
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("hq rescue -y --paths .claude"));
+    expect(rescueMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("preserves settings.local.json and personal drift while restoring hook wiring", async () => {
+    const root = makeHqRoot({ customSetting: true, hooks: {} });
+    const localSettings = '{"localOnly":true}\n';
+    const personalEdit = "keep this user policy\n";
+    fs.writeFileSync(path.join(root, ".claude", "settings.local.json"), localSettings);
+    fs.writeFileSync(path.join(root, "personal", "policy.md"), personalEdit);
+
+    await run("--repo-root", root);
+
+    expect(fs.readFileSync(path.join(root, ".claude", "settings.local.json"), "utf8")).toBe(localSettings);
+    expect(fs.readFileSync(path.join(root, "personal", "policy.md"), "utf8")).toBe(personalEdit);
+    expect(JSON.parse(fs.readFileSync(path.join(root, "personal", "settings.json"), "utf8"))).toEqual({
+      customSetting: true,
+      hooks: {},
+    });
+    expect(logSpy).toHaveBeenCalledWith("reindex: repaired HQ hook config");
+  });
+
+  it("warns without changing partial hook wiring", async () => {
+    const root = makeHqRoot({
+      hooks: {
+        SessionStart: [{ hooks: [{ type: "command", command: "echo start" }] }],
+      },
+    });
+
+    await run("--repo-root", root);
+
+    expect(rescueMock).not.toHaveBeenCalled();
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("missing command hook wiring"));
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("settingSources"));
+  });
+
+  it("uses the shipped hook checker when the resolved HQ root contains it", async () => {
+    const root = makeHqRoot();
+    const checker = path.join(root, "core", "scripts", "check-hq-hooks.sh");
+    fs.mkdirSync(path.dirname(checker), { recursive: true });
+    fs.writeFileSync(checker, 'printf checked > "$2/.claude/checker-ran"\n');
+
+    await run("--repo-root", root);
+
+    expect(fs.readFileSync(path.join(root, ".claude", "checker-ran"), "utf8")).toBe("checked");
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("surfaces diagnostics when the shipped hook checker fails", async () => {
+    const root = makeHqRoot();
+    const checker = path.join(root, "core", "scripts", "check-hq-hooks.sh");
+    fs.mkdirSync(path.dirname(checker), { recursive: true });
+    fs.writeFileSync(checker, 'echo "scaffold detected drift" >&2\nexit 2\n');
+
+    await run("--repo-root", root);
+
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("scaffold detected drift"));
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("hq rescue -y --paths .claude"));
+  });
+});

package/src/commands/reindex.ts

@@ -22,8 +22,213 @@
  * operation lock honors, so it works even against an installed hq-cloud build
  * that predates a typed lock-timeout option.
  */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 import { Command } from 'commander';
-import { reindex } from '@indigoai-us/hq-cloud';
+import * as yaml from 'js-yaml';
+import { reindex, rescue } from '@indigoai-us/hq-cloud';
+import { findHqRoot } from '../utils/manifest.js';
+
+const HOOK_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse'] as const;
+const HOOK_CHECK_RELATIVE_PATH = path.join('core', 'scripts', 'check-hq-hooks.sh');
+
+type HookHealth =
+  | { state: 'healthy' }
+  | { state: 'extreme'; reason: string }
+  | { state: 'minor'; reason: string };
+
+type HookCheckResult = { status: number; output: string };
+
+/** Resolve the same root the repair/check commands must operate on. */
+function resolveHqRoot(repoRoot?: string): string {
+  const root = repoRoot ?? findHqRoot();
+  try {
+    return fs.realpathSync(root);
+  } catch {
+    return path.resolve(root);
+  }
+}
+
+function isHqRoot(hqRoot: string): boolean {
+  return (
+    fs.existsSync(path.join(hqRoot, 'companies')) &&
+    (fs.existsSync(path.join(hqRoot, '.claude')) ||
+      fs.existsSync(path.join(hqRoot, 'core')) ||
+      fs.existsSync(path.join(hqRoot, 'personal')))
+  );
+}
+
+function hasCommandHook(value: unknown): boolean {
+  if (!Array.isArray(value)) return false;
+  return value.some((entry) => {
+    if (!entry || typeof entry !== 'object') return false;
+    const hooks = (entry as { hooks?: unknown }).hooks;
+    if (!Array.isArray(hooks)) return false;
+    return hooks.some(
+      (hook) =>
+        !!hook &&
+        typeof hook === 'object' &&
+        (hook as { type?: unknown }).type === 'command' &&
+        typeof (hook as { command?: unknown }).command === 'string' &&
+        (hook as { command: string }).command.trim().length > 0
+    );
+  });
+}
+
+/**
+ * Run the release health checker when it is available. Its diagnostics cover
+ * runtime/configuration issues outside the safe repair scope; the JSON check
+ * below additionally recognizes UserPromptSubmit, which older checkers omit.
+ */
+function runShippedHookCheck(hqRoot: string): HookCheckResult | undefined {
+  const checker = path.join(hqRoot, HOOK_CHECK_RELATIVE_PATH);
+  if (!fs.existsSync(checker)) return undefined;
+
+  try {
+    const result = spawnSync('bash', [checker, '--root', hqRoot], {
+      encoding: 'utf8',
+      stdio: 'pipe',
+    });
+    if (result.error) return undefined;
+    return {
+      status: result.status ?? 1,
+      output: `${result.stderr ?? ''}${result.stdout ?? ''}`.trim(),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function inspectHookHealth(hqRoot: string): HookHealth {
+  const checkerResult = runShippedHookCheck(hqRoot);
+  const settingsPath = path.join(hqRoot, '.claude', 'settings.json');
+  if (!fs.existsSync(settingsPath)) {
+    return { state: 'extreme', reason: '.claude/settings.json is missing' };
+  }
+
+  let settings: unknown;
+  try {
+    settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  } catch {
+    return { state: 'minor', reason: '.claude/settings.json is not valid JSON' };
+  }
+  if (!settings || typeof settings !== 'object') {
+    return { state: 'minor', reason: '.claude/settings.json is not an object' };
+  }
+
+  const hooks = (settings as { hooks?: unknown }).hooks;
+  if (!hooks || typeof hooks !== 'object') {
+    return { state: 'extreme', reason: 'no command hooks are declared' };
+  }
+
+  const commandEvents = HOOK_EVENTS.filter((event) =>
+    hasCommandHook((hooks as Record<string, unknown>)[event])
+  );
+  if (commandEvents.length === 0) {
+    return { state: 'extreme', reason: 'no SessionStart, UserPromptSubmit, or PreToolUse command hook is declared' };
+  }
+  if (commandEvents.length !== HOOK_EVENTS.length) {
+    return {
+      state: 'minor',
+      reason: `missing command hook wiring for ${HOOK_EVENTS.filter((event) => !commandEvents.includes(event)).join(', ')}`,
+    };
+  }
+
+  if (checkerResult !== undefined && checkerResult.status !== 0) {
+    return {
+      state: 'minor',
+      reason: checkerResult.output || 'the shipped core/scripts/check-hq-hooks.sh check failed',
+    };
+  }
+  return { state: 'healthy' };
+}
+
+function printHookHealthWarning(hqRoot: string, reason: string): void {
+  console.warn(`
+HQ hook health warning: lifecycle hooks may not fire in ${hqRoot}.
+  - ${reason}
+
+Repair the project settings with:
+  hq rescue -y --paths .claude
+
+If the repair is unavailable, update HQ and re-run \`hq reindex\`.
+For Claude Desktop, open the HQ root itself as the project (not a parent or child folder).
+For an SDK launch, set both \`cwd\` to the HQ root and \`settingSources: ["project"]\`.
+See core/docs/hq/HOOKS-NOT-FIRING.md for the recovery procedure.`);
+}
+
+function installedCoreRef(hqRoot: string): string | undefined {
+  for (const relativePath of [path.join('core', 'core.yaml'), 'core.yaml']) {
+    try {
+      const core = yaml.load(fs.readFileSync(path.join(hqRoot, relativePath), 'utf8')) as
+        | { hqVersion?: unknown }
+        | undefined;
+      if (typeof core?.hqVersion === 'string' && core.hqVersion.trim()) {
+        return core.hqVersion.startsWith('v') ? core.hqVersion : `v${core.hqVersion}`;
+      }
+    } catch {
+      // The installed version is optional; rescue will use the production default.
+    }
+  }
+  return undefined;
+}
+
+/** Rescue writes detailed progress directly to stdio. Reindex only needs a one-line notice. */
+function runSilently<T>(operation: () => T): T {
+  const writeStdout = process.stdout.write;
+  const writeStderr = process.stderr.write;
+  const discard = (() => true) as typeof process.stdout.write;
+  process.stdout.write = discard;
+  process.stderr.write = discard;
+  try {
+    return operation();
+  } finally {
+    process.stdout.write = writeStdout;
+    process.stderr.write = writeStderr;
+  }
+}
+
+/**
+ * Check hook health without relying on lifecycle hooks. A fully disabled
+ * configuration is repaired only after a successful reindex; partial and
+ * malformed configurations remain untouched and receive recovery guidance.
+ */
+export function repairExtremeHookDrift(hqRoot: string, allowRepair = true): void {
+  // `hq reindex` can still be invoked from an arbitrary directory. Never turn
+  // an absent settings file there into a rescue attempt.
+  if (!isHqRoot(hqRoot)) return;
+
+  const health = inspectHookHealth(hqRoot);
+  if (health.state === 'healthy') return;
+
+  printHookHealthWarning(hqRoot, health.reason);
+  if (health.state === 'minor' || !allowRepair) return;
+
+  try {
+    const result = runSilently(() =>
+      rescue({
+        hqRoot,
+        source: 'indigoai-us/hq-core',
+        ref: installedCoreRef(hqRoot),
+        paths: ['.claude'],
+        assumeYes: true,
+      })
+    );
+    const afterRepair = inspectHookHealth(hqRoot);
+    if (result.status === 0 && afterRepair.state === 'healthy') {
+      console.log('reindex: repaired HQ hook config');
+      return;
+    }
+    printHookHealthWarning(
+      hqRoot,
+      afterRepair.state === 'healthy' ? `rescue exited ${result.status}` : afterRepair.reason
+    );
+  } catch {
+    // A transient clone/transport failure must not turn reindex into a fatal command.
+    printHookHealthWarning(hqRoot, 'hook configuration repair could not run');
+  }
+}
 
 export function registerReindexCommand(program: Command): void {
   program
@@ -63,6 +268,7 @@ export function registerReindexCommand(program: Command): void {
       }
 
       const { status } = reindex({ repoRoot: opts.repoRoot });
+      repairExtremeHookDrift(resolveHqRoot(opts.repoRoot), status === 0);
       process.exit(status);
     });
 }