@indigoai-us/hq-cli 5.77.6 → 5.77.7

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);
     });
 }

package/src/utils/version-gate.test.ts

@@ -436,4 +436,180 @@ describe("enforceVersionGate — hard-update path", () => {
     expect(exitSpy).toHaveBeenCalledWith(75);
     expect(runner).toHaveBeenCalledWith("sudo", expect.arrayContaining(["-n"]));
   });
+
+  it("cleans a stale partial install and retries once when the unprivileged install fails with ENOTEMPTY", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const exitSpy = vi
+      .spyOn(process, "exit")
+      .mockImplementation(((code?: number) => {
+        throw new Error(`__process_exit__:${code ?? 0}`);
+      }) as never);
+    // The reported failure: `npm install -g --prefix <toolchain> …` fails with
+    // ENOTEMPTY renaming a partial `hq-cli`. sudo does NOT fix a corrupt dir —
+    // only removing the stale artifacts and reinstalling does. Before this fix
+    // the gate exhausted npm→sudo→exit 75, leaving `hq` broken (ENOENT).
+    let npmCalls = 0;
+    const runner = vi.fn().mockImplementation((cmd: string) => {
+      if (cmd === "sudo") return { ok: false, detail: "ENOTEMPTY" };
+      npmCalls += 1;
+      return npmCalls === 1 ? { ok: false, detail: "ENOTEMPTY" } : { ok: true };
+    });
+    const prefix =
+      "/Users/x/Library/Application Support/Indigo HQ/toolchain/npm-global";
+    const cleanStale = vi
+      .fn()
+      .mockReturnValue([`${prefix}/lib/node_modules/@indigoai-us/.hq-cli-0DY3ww6z`]);
+    const { __test__ } = await loadModule();
+
+    expect(() =>
+      __test__.enforceUpdateRequired(
+        {
+          clientId: "hq-cli",
+          currentVersion: "5.10.0",
+          minVersion: "5.20.0",
+          latestVersion: "5.24.0",
+          updateRequired: true,
+          updateRecommended: false,
+          updateCommand: "npm install -g @indigoai-us/hq-cli@latest",
+        },
+        { resolvePrefix: () => prefix, runner, cleanStale },
+      ),
+    ).toThrow(/__process_exit__:0/); // recovers after the cleanup + retry
+
+    expect(exitSpy).toHaveBeenCalledWith(0);
+    expect(cleanStale).toHaveBeenCalledWith(prefix);
+    const installArgs = [
+      "install",
+      "-g",
+      "--prefix",
+      prefix,
+      "@indigoai-us/hq-cli@latest",
+    ];
+    // primary attempt + one retry after the stale artifacts were removed
+    expect(
+      runner.mock.calls.filter((c) => c[0] === "npm").length,
+    ).toBe(2);
+    expect(runner).toHaveBeenCalledWith("npm", installArgs);
+    // sudo must NOT be reached — the ENOTEMPTY was fixed by cleanup, not perms
+    expect(runner).not.toHaveBeenCalledWith("sudo", expect.anything());
+  });
+
+  it("does NOT reinstall-after-clean when nothing stale exists (plain EACCES falls straight to sudo)", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const exitSpy = vi
+      .spyOn(process, "exit")
+      .mockImplementation(((code?: number) => {
+        throw new Error(`__process_exit__:${code ?? 0}`);
+      }) as never);
+    const runner = vi
+      .fn()
+      .mockImplementation((cmd: string) =>
+        cmd === "sudo" ? { ok: true } : { ok: false, detail: "EACCES" },
+      );
+    const cleanStale = vi.fn().mockReturnValue([]); // healthy prefix, nothing to remove
+    const { __test__ } = await loadModule();
+
+    expect(() =>
+      __test__.enforceUpdateRequired(
+        {
+          clientId: "hq-cli",
+          currentVersion: "5.10.0",
+          minVersion: "5.20.0",
+          latestVersion: "5.24.0",
+          updateRequired: true,
+          updateRecommended: false,
+          updateCommand: "npm install -g @indigoai-us/hq-cli@latest",
+        },
+        { resolvePrefix: () => "/usr", runner, cleanStale },
+      ),
+    ).toThrow(/__process_exit__:0/); // sudo retry succeeds
+
+    expect(exitSpy).toHaveBeenCalledWith(0);
+    expect(cleanStale).toHaveBeenCalledWith("/usr");
+    // exactly ONE npm attempt (no redundant reinstall), then sudo
+    expect(runner.mock.calls.filter((c) => c[0] === "npm").length).toBe(1);
+    expect(runner).toHaveBeenCalledWith("sudo", expect.arrayContaining(["-n"]));
+  });
+});
+
+describe("cleanStalePartialInstall", () => {
+  type FakeTree = {
+    dirs: Record<string, string[]>;
+    packageJson: Record<string, string | null>;
+    existing: Set<string>;
+  };
+
+  function makeFakeFs(tree: FakeTree) {
+    const removed: string[] = [];
+    const fs = {
+      readdirSync: (dir: string) => {
+        if (dir in tree.dirs) return tree.dirs[dir]!;
+        throw new Error(`ENOENT: ${dir}`);
+      },
+      existsSync: (target: string) => tree.existing.has(target),
+      readFileSync: (target: string) => {
+        const pkgDir = target.replace(/\/package\.json$/, "");
+        const content = tree.packageJson[pkgDir];
+        if (content == null) throw new Error(`ENOENT: ${target}`);
+        return content;
+      },
+      rmSync: (target: string) => {
+        removed.push(target);
+      },
+    };
+    return { fs, removed };
+  }
+
+  it("removes the npm staging dir and a partial package dir, but keeps unrelated entries", async () => {
+    const { __test__ } = await loadModule();
+    const prefix = "/p";
+    const scopeDir = "/p/lib/node_modules/@indigoai-us";
+    const { fs, removed } = makeFakeFs({
+      dirs: {
+        [scopeDir]: [".hq-cli-0DY3ww6z", "hq-cli", "some-other-pkg"],
+      },
+      packageJson: { [`${scopeDir}/hq-cli`]: null }, // partial: package.json unreadable
+      existing: new Set([`${scopeDir}/hq-cli`]),
+    });
+
+    const result = __test__.cleanStalePartialInstall(prefix, fs);
+
+    expect(result).toContain(`${scopeDir}/.hq-cli-0DY3ww6z`);
+    expect(result).toContain(`${scopeDir}/hq-cli`);
+    expect(removed).not.toContain(`${scopeDir}/some-other-pkg`);
+  });
+
+  it("never touches a healthy install (valid package.json with matching name)", async () => {
+    const { __test__ } = await loadModule();
+    const scopeDir = "/p/lib/node_modules/@indigoai-us";
+    const { fs, removed } = makeFakeFs({
+      dirs: { [scopeDir]: ["hq-cli"] }, // no staging leftovers
+      packageJson: {
+        [`${scopeDir}/hq-cli`]: JSON.stringify({
+          name: "@indigoai-us/hq-cli",
+          version: "5.24.0",
+        }),
+      },
+      existing: new Set([`${scopeDir}/hq-cli`]),
+    });
+
+    const result = __test__.cleanStalePartialInstall("/p", fs);
+
+    expect(result).toEqual([]);
+    expect(removed).toEqual([]);
+  });
+
+  it("also cleans a staging dir under the bare <prefix>/node_modules layout", async () => {
+    const { __test__ } = await loadModule();
+    const scopeDir = "/p/node_modules/@indigoai-us";
+    const { fs } = makeFakeFs({
+      dirs: { [scopeDir]: [".hq-cli-abc123"] },
+      packageJson: {},
+      existing: new Set(),
+    });
+
+    const result = __test__.cleanStalePartialInstall("/p", fs);
+
+    expect(result).toEqual([`${scopeDir}/.hq-cli-abc123`]);
+  });
 });