@indigoai-us/hq-cli 5.77.14 → 5.78.0

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

@@ -1,1024 +0,0 @@
-/**
- * Tests for the version-gate module. Hermetic — no network, no spawn.
- *
- * Pinning CLI_VERSION via the same mock pattern used by version-check.test.ts
- * (`vi.mock('../cli-version.js', …)`) so the gate request body is
- * deterministic.
- */
-
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-
-vi.mock("../cli-version.js", () => ({
-  CLI_VERSION: "5.10.0",
-  CLI_NAME: "@indigoai-us/hq-cli",
-}));
-
-beforeEach(() => {
-  vi.unstubAllEnvs();
-  vi.restoreAllMocks();
-});
-
-afterEach(() => {
-  vi.unstubAllEnvs();
-  vi.restoreAllMocks();
-});
-
-async function loadModule() {
-  vi.resetModules();
-  return await import("./version-gate.js");
-}
-
-/**
- * `RunningInstall` fixtures. `resolveRunningInstall()` is the single
- * package-root walk the gate performs, so tests inject its result rather than
- * a manager and a prefix separately.
- */
-function npmInstall(prefix: string | null) {
-  return { manager: "npm" as const, prefix, packageRoot: null };
-}
-
-function pnpmInstall() {
-  // pnpm-managed installs never carry a prefix — see resolveRunningInstall().
-  return {
-    manager: "pnpm" as const,
-    prefix: null,
-    packageRoot:
-      "/Users/x/Library/pnpm/global/5/.pnpm/@indigoai-us+hq-cli@5.61.0/node_modules/@indigoai-us/hq-cli",
-  };
-}
-
-describe("shouldSkipGate", () => {
-  it("returns true for --version", async () => {
-    const { shouldSkipGate } = await loadModule();
-    expect(shouldSkipGate(["node", "hq", "--version"])).toBe(true);
-  });
-
-  it("returns true for -V, -v, --help, -h", async () => {
-    const { shouldSkipGate } = await loadModule();
-    expect(shouldSkipGate(["node", "hq", "-V"])).toBe(true);
-    expect(shouldSkipGate(["node", "hq", "-v"])).toBe(true);
-    expect(shouldSkipGate(["node", "hq", "--help"])).toBe(true);
-    expect(shouldSkipGate(["node", "hq", "-h"])).toBe(true);
-  });
-
-  it("returns false for a regular subcommand", async () => {
-    const { shouldSkipGate } = await loadModule();
-    expect(shouldSkipGate(["node", "hq", "sync"])).toBe(false);
-    expect(shouldSkipGate(["node", "hq", "members", "list"])).toBe(false);
-  });
-});
-
-describe("prefix install helpers", () => {
-  it("derives the npm prefix from unix global package layouts", async () => {
-    const { __test__ } = await loadModule();
-    expect(
-      __test__.npmPrefixFromPackageDir(
-        "/Users/x/Library/Application Support/Indigo HQ/toolchain/npm-global/lib/node_modules/@indigoai-us/hq-cli",
-      ),
-    ).toBe("/Users/x/Library/Application Support/Indigo HQ/toolchain/npm-global");
-    expect(
-      __test__.npmPrefixFromPackageDir(
-        "/usr/local/lib/node_modules/@indigoai-us/hq-cli",
-      ),
-    ).toBe("/usr/local");
-  });
-
-  it("derives the npm prefix from a windows-style package layout", async () => {
-    const { __test__ } = await loadModule();
-    expect(
-      __test__.npmPrefixFromPackageDir(
-        "C:\\Users\\x\\AppData\\Roaming\\npm\\node_modules\\@indigoai-us\\hq-cli",
-      ),
-    ).toBe("C:/Users/x/AppData/Roaming/npm");
-  });
-
-  it("returns null when the package path is not under node_modules", async () => {
-    const { __test__ } = await loadModule();
-    expect(
-      __test__.npmPrefixFromPackageDir(
-        "/Users/x/dev/hq/packages/hq-cli",
-      ),
-    ).toBeNull();
-  });
-
-  it("builds the prefixed npm install argv", async () => {
-    const { __test__ } = await loadModule();
-    expect(__test__.buildPrefixedInstallArgv("/tmp/npm-global")).toEqual([
-      "install",
-      "-g",
-      "--prefix",
-      "/tmp/npm-global",
-      "@indigoai-us/hq-cli@latest",
-    ]);
-  });
-});
-
-describe("enforceVersionGate — opt-out + soft paths (no process.exit)", () => {
-  it("is silent + no fetch when HQ_NO_UPDATE_CHECK=1", async () => {
-    vi.stubEnv("HQ_NO_UPDATE_CHECK", "1");
-    const fetchMock = vi.fn();
-    vi.stubGlobal("fetch", fetchMock);
-    const { enforceVersionGate } = await loadModule();
-    await enforceVersionGate();
-    expect(fetchMock).not.toHaveBeenCalled();
-  });
-
-  it("is silent on non-200 response (treats as no-gate)", async () => {
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockResolvedValue(
-        new Response("", { status: 500 }),
-      ),
-    );
-    // process.exit must HALT execution — mocking it as undefined lets code
-    // fall through past the exit point and crash on later lines. Throwing a
-    // sentinel error reproduces the "never returns" semantics in unit tests.
-    const exitSpy = vi
-      .spyOn(process, "exit")
-      .mockImplementation(((code?: number) => {
-        throw new Error(`__process_exit__:${code ?? 0}`);
-      }) as never);
-    const { enforceVersionGate } = await loadModule();
-    await enforceVersionGate();
-    expect(exitSpy).not.toHaveBeenCalled();
-  });
-
-  it("is silent on malformed response body", async () => {
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockResolvedValue(
-        new Response(JSON.stringify({ ok: true }), { status: 200 }),
-      ),
-    );
-    // process.exit must HALT execution — mocking it as undefined lets code
-    // fall through past the exit point and crash on later lines. Throwing a
-    // sentinel error reproduces the "never returns" semantics in unit tests.
-    const exitSpy = vi
-      .spyOn(process, "exit")
-      .mockImplementation(((code?: number) => {
-        throw new Error(`__process_exit__:${code ?? 0}`);
-      }) as never);
-    const { enforceVersionGate } = await loadModule();
-    await enforceVersionGate();
-    expect(exitSpy).not.toHaveBeenCalled();
-  });
-
-  it("is silent on fetch rejection (network down / timeout)", async () => {
-    vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("network down")));
-    // process.exit must HALT execution — mocking it as undefined lets code
-    // fall through past the exit point and crash on later lines. Throwing a
-    // sentinel error reproduces the "never returns" semantics in unit tests.
-    const exitSpy = vi
-      .spyOn(process, "exit")
-      .mockImplementation(((code?: number) => {
-        throw new Error(`__process_exit__:${code ?? 0}`);
-      }) as never);
-    const { enforceVersionGate } = await loadModule();
-    await expect(enforceVersionGate()).resolves.toBeUndefined();
-    expect(exitSpy).not.toHaveBeenCalled();
-  });
-
-  it("nudges on updateRecommended without exiting", async () => {
-    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
-    // process.exit must HALT execution — mocking it as undefined lets code
-    // fall through past the exit point and crash on later lines. Throwing a
-    // sentinel error reproduces the "never returns" semantics in unit tests.
-    const exitSpy = vi
-      .spyOn(process, "exit")
-      .mockImplementation(((code?: number) => {
-        throw new Error(`__process_exit__:${code ?? 0}`);
-      }) as never);
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockResolvedValue(
-        new Response(
-          JSON.stringify({
-            clientId: "hq-cli",
-            currentVersion: "5.10.0",
-            minVersion: "5.0.0",
-            latestVersion: "5.24.0",
-            updateRequired: false,
-            updateRecommended: true,
-            updateCommand: "npm install -g @indigoai-us/hq-cli@latest",
-          }),
-          { status: 200 },
-        ),
-      ),
-    );
-    const { enforceVersionGate } = await loadModule();
-    await enforceVersionGate();
-    expect(exitSpy).not.toHaveBeenCalled();
-    const printed = errSpy.mock.calls.map((c) => c.join(" ")).join("\n");
-    expect(printed).toContain("5.24.0");
-  });
-
-  it("does NOT nudge or block when current = latest", async () => {
-    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
-    // process.exit must HALT execution — mocking it as undefined lets code
-    // fall through past the exit point and crash on later lines. Throwing a
-    // sentinel error reproduces the "never returns" semantics in unit tests.
-    const exitSpy = vi
-      .spyOn(process, "exit")
-      .mockImplementation(((code?: number) => {
-        throw new Error(`__process_exit__:${code ?? 0}`);
-      }) as never);
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockResolvedValue(
-        new Response(
-          JSON.stringify({
-            clientId: "hq-cli",
-            currentVersion: "5.10.0",
-            minVersion: "5.0.0",
-            latestVersion: "5.10.0",
-            updateRequired: false,
-            updateRecommended: false,
-          }),
-          { status: 200 },
-        ),
-      ),
-    );
-    const { enforceVersionGate } = await loadModule();
-    await enforceVersionGate();
-    expect(exitSpy).not.toHaveBeenCalled();
-    expect(errSpy).not.toHaveBeenCalled();
-  });
-});
-
-describe("enforceVersionGate — hard-update path", () => {
-  it("calls process.exit when updateRequired is true and no updateCommand", async () => {
-    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
-    // process.exit must HALT execution — mocking it as undefined lets code
-    // fall through past the exit point and crash on later lines. Throwing a
-    // sentinel error reproduces the "never returns" semantics in unit tests.
-    const exitSpy = vi
-      .spyOn(process, "exit")
-      .mockImplementation(((code?: number) => {
-        throw new Error(`__process_exit__:${code ?? 0}`);
-      }) as never);
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockResolvedValue(
-        new Response(
-          JSON.stringify({
-            clientId: "hq-cli",
-            currentVersion: "5.10.0",
-            minVersion: "5.20.0",
-            latestVersion: "5.24.0",
-            updateRequired: true,
-            updateRecommended: false,
-            // no updateCommand — exits with code 75 (manual update needed)
-          }),
-          { status: 200 },
-        ),
-      ),
-    );
-    const { enforceVersionGate } = await loadModule();
-    await expect(enforceVersionGate()).rejects.toThrow(/__process_exit__:75/);
-    expect(exitSpy).toHaveBeenCalledWith(75);
-    const printed = errSpy.mock.calls.map((c) => c.join(" ")).join("\n");
-    expect(printed).toContain("below the minimum");
-  });
-
-  it("posts the expected request body to /v1/client-version/check", async () => {
-    const fetchMock = vi.fn().mockResolvedValue(
-      new Response(
-        JSON.stringify({
-          clientId: "hq-cli",
-          currentVersion: "5.10.0",
-          minVersion: "5.0.0",
-          latestVersion: "5.10.0",
-          updateRequired: false,
-          updateRecommended: false,
-        }),
-        { status: 200 },
-      ),
-    );
-    vi.stubGlobal("fetch", fetchMock);
-    const { enforceVersionGate } = await loadModule();
-    await enforceVersionGate();
-
-    expect(fetchMock).toHaveBeenCalledTimes(1);
-    const [url, init] = fetchMock.mock.calls[0]!;
-    expect(String(url)).toContain("/v1/client-version/check");
-    const body = JSON.parse((init as RequestInit).body as string);
-    expect(body.clientId).toBe("hq-cli");
-    expect(body.currentVersion).toBe("5.10.0");
-    expect(typeof body.platform).toBe("string");
-  });
-
-  it("installs with the resolved running prefix instead of the bare server command", 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().mockReturnValue({ ok: true });
-    const { __test__ } = await loadModule();
-    const prefix = "/Users/x/Library/Application Support/Indigo HQ/toolchain/npm-global";
-
-    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",
-        },
-        {
-          resolveInstall: () => npmInstall(prefix),
-          runner,
-        },
-      ),
-    ).toThrow(/__process_exit__:0/);
-
-    expect(exitSpy).toHaveBeenCalledWith(0);
-    expect(runner).toHaveBeenCalledWith("npm", [
-      "install",
-      "-g",
-      "--prefix",
-      prefix,
-      "@indigoai-us/hq-cli@latest",
-    ]);
-    expect(runner).not.toHaveBeenCalledWith("npm", [
-      "install",
-      "-g",
-      "@indigoai-us/hq-cli@latest",
-    ]);
-  });
-
-  it("falls back to the server updateCommand when no running prefix resolves", 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 performUpdateString = vi.fn().mockReturnValue({ ok: true });
-    const { __test__ } = await loadModule();
-    const updateCommand = "npm install -g @indigoai-us/hq-cli@latest";
-
-    expect(() =>
-      __test__.enforceUpdateRequired(
-        {
-          clientId: "hq-cli",
-          currentVersion: "5.10.0",
-          minVersion: "5.20.0",
-          latestVersion: "5.24.0",
-          updateRequired: true,
-          updateRecommended: false,
-          updateCommand,
-        },
-        {
-          performUpdateString,
-          resolveInstall: () => npmInstall(null),
-        },
-      ),
-    ).toThrow(/__process_exit__:0/);
-
-    expect(exitSpy).toHaveBeenCalledWith(0);
-    expect(performUpdateString).toHaveBeenCalledWith(updateCommand);
-  });
-
-  it("retries under `sudo -n` when the unprivileged install fails (root-owned global)", async () => {
-    vi.spyOn(console, "error").mockImplementation(() => {});
-    const exitSpy = vi
-      .spyOn(process, "exit")
-      .mockImplementation(((code?: number) => {
-        throw new Error(`__process_exit__:${code ?? 0}`);
-      }) as never);
-    // First (unprivileged) npm install fails with EACCES; the sudo -n retry succeeds.
-    const runner = vi
-      .fn()
-      .mockImplementation((cmd: string) =>
-        cmd === "sudo" ? { ok: true } : { ok: false, detail: "EACCES" },
-      );
-    const { __test__ } = await loadModule();
-    const prefix = "/usr";
-
-    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",
-        },
-        { resolveInstall: () => npmInstall(prefix), runner },
-      ),
-    ).toThrow(/__process_exit__:0/); // succeeds after the sudo retry
-
-    expect(exitSpy).toHaveBeenCalledWith(0);
-    const installArgs = [
-      "install",
-      "-g",
-      "--prefix",
-      prefix,
-      "@indigoai-us/hq-cli@latest",
-    ];
-    expect(runner).toHaveBeenCalledWith("npm", installArgs);
-    expect(runner).toHaveBeenCalledWith("sudo", ["-n", "npm", ...installArgs]);
-  });
-
-  it("exits 75 when BOTH the unprivileged install and the sudo -n retry fail", 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().mockReturnValue({ ok: false, detail: "EACCES" });
-    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",
-        },
-        { resolveInstall: () => npmInstall("/usr"), runner },
-      ),
-    ).toThrow(/__process_exit__:75/);
-
-    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",
-        },
-        { resolveInstall: () => npmInstall(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",
-        },
-        { resolveInstall: () => npmInstall("/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`]);
-  });
-});
-
-// Regression coverage for feedback_812a6727: a pnpm-managed global install kept
-// reporting the old version after every "successful" self-update, because the
-// gate derived an npm --prefix from the pnpm store and installed into a
-// directory the pnpm PATH shim never reads.
-describe("pnpm-managed global installs", () => {
-  const PNPM_STORE_DIR =
-    "/Users/x/Library/pnpm/global/5/.pnpm/@indigoai-us+hq-cli@5.61.0/node_modules/@indigoai-us/hq-cli";
-  const PNPM_LINK_DIR =
-    "/Users/x/Library/pnpm/global/5/node_modules/@indigoai-us/hq-cli";
-
-  it("recognises both the store and the symlinked pnpm global layouts", async () => {
-    const { __test__ } = await loadModule();
-    expect(__test__.isPnpmManagedPackageDir(PNPM_STORE_DIR)).toBe(true);
-    expect(__test__.isPnpmManagedPackageDir(PNPM_LINK_DIR)).toBe(true);
-    expect(
-      __test__.isPnpmManagedPackageDir(
-        "C:\\Users\\x\\AppData\\Local\\pnpm\\global\\5\\node_modules\\@indigoai-us\\hq-cli",
-      ),
-    ).toBe(true);
-  });
-
-  it("does not mistake an npm global layout for a pnpm one", async () => {
-    const { __test__ } = await loadModule();
-    expect(
-      __test__.isPnpmManagedPackageDir(
-        "/usr/local/lib/node_modules/@indigoai-us/hq-cli",
-      ),
-    ).toBe(false);
-    expect(
-      __test__.isPnpmManagedPackageDir(
-        "/Users/x/.nvm/versions/node/v22.3.0/lib/node_modules/@indigoai-us/hq-cli",
-      ),
-    ).toBe(false);
-    // A project that merely depends on pnpm-named packages is still npm-shaped.
-    expect(
-      __test__.isPnpmManagedPackageDir(
-        "/Users/x/code/pnpm-tools/node_modules/@indigoai-us/hq-cli",
-      ),
-    ).toBe(false);
-  });
-
-  it("demonstrates the old bug: a pnpm store path yields a plausible-looking npm prefix", async () => {
-    const { __test__ } = await loadModule();
-    // npmPrefixFromPackageDir is layout-blind — it happily hands back the pnpm
-    // store as if it were an npm prefix, which is exactly what made
-    // `npm install -g --prefix <store>` exit 0 while changing nothing the shim
-    // resolves. The manager check is what has to stop that.
-    expect(__test__.npmPrefixFromPackageDir(PNPM_STORE_DIR)).not.toBeNull();
-    expect(__test__.npmPrefixFromPackageDir(PNPM_LINK_DIR)).not.toBeNull();
-    expect(__test__.isPnpmManagedPackageDir(PNPM_STORE_DIR)).toBe(true);
-    expect(__test__.isPnpmManagedPackageDir(PNPM_LINK_DIR)).toBe(true);
-  });
-
-  it("builds the pnpm global install argv", async () => {
-    const { __test__ } = await loadModule();
-    expect(__test__.buildPnpmInstallArgv()).toEqual([
-      "add",
-      "-g",
-      "@indigoai-us/hq-cli@latest",
-    ]);
-  });
-
-  it("updates with `pnpm add -g` and never npm-installs into the pnpm store", 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().mockReturnValue({ ok: true });
-    const performUpdateString = vi.fn().mockReturnValue({ ok: true });
-    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",
-        },
-        {
-          resolveInstall: () => pnpmInstall(),
-          performUpdateString,
-          runner,
-        },
-      ),
-    ).toThrow(/__process_exit__:0/);
-
-    expect(exitSpy).toHaveBeenCalledWith(0);
-    expect(runner).toHaveBeenCalledWith("pnpm", [
-      "add",
-      "-g",
-      "@indigoai-us/hq-cli@latest",
-    ]);
-    // No npm anywhere: not the prefixed form, not the server's command.
-    expect(runner).not.toHaveBeenCalledWith("npm", expect.anything());
-    expect(performUpdateString).not.toHaveBeenCalled();
-  });
-
-  it("exits 75 without a sudo retry when the pnpm update fails", 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().mockReturnValue({ ok: false, detail: "EACCES" });
-    const cleanStale = vi.fn().mockReturnValue([]);
-    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",
-        },
-        {
-          resolveInstall: () => pnpmInstall(),
-          runner,
-          cleanStale,
-        },
-      ),
-    ).toThrow(/__process_exit__:75/);
-
-    expect(exitSpy).toHaveBeenCalledWith(75);
-    // `sudo -n pnpm add -g` would install into root's PNPM_HOME and report
-    // success while the user's shim stayed stale — the failure must surface.
-    expect(runner).not.toHaveBeenCalledWith("sudo", expect.anything());
-    expect(cleanStale).not.toHaveBeenCalled();
-    expect(runner.mock.calls.every((c) => c[0] === "pnpm")).toBe(true);
-  });
-
-  it("still uses npm when the running install is npm-managed", async () => {
-    vi.spyOn(console, "error").mockImplementation(() => {});
-    vi.spyOn(process, "exit").mockImplementation(((code?: number) => {
-      throw new Error(`__process_exit__:${code ?? 0}`);
-    }) as never);
-    const runner = vi.fn().mockReturnValue({ ok: true });
-    const { __test__ } = await loadModule();
-    const prefix = "/usr/local";
-
-    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",
-        },
-        { resolveInstall: () => npmInstall(prefix), runner },
-      ),
-    ).toThrow(/__process_exit__:0/);
-
-    expect(runner).toHaveBeenCalledWith("npm", [
-      "install",
-      "-g",
-      "--prefix",
-      prefix,
-      "@indigoai-us/hq-cli@latest",
-    ]);
-    expect(runner).not.toHaveBeenCalledWith("pnpm", expect.anything());
-  });
-});
-
-// Second round of regression coverage for feedback_812a6727. The first fix made
-// only the HARD gate (updateRequired) pnpm-aware; everything below closes the
-// paths that could still reproduce the reported stale-shim loop, or that the
-// pnpm branch newly mis-handled.
-describe("pnpm-managed installs — soft nudge path", () => {
-  const decision = {
-    clientId: "hq-cli",
-    currentVersion: "5.10.0",
-    minVersion: "5.0.0",
-    latestVersion: "5.24.0",
-    updateRequired: false,
-    updateRecommended: true,
-    updateCommand: "npm install -g @indigoai-us/hq-cli@latest",
-  };
-
-  it("never tells a pnpm-managed install to run an npm command", async () => {
-    // updateRecommended fires for EVERY version below latest, while
-    // updateRequired only fires below minVersion — so this is the path a real
-    // user hits first. Printing the server's npm-shaped command here installs a
-    // fresh copy under the npm global prefix while pnpm's PATH shim keeps
-    // resolving the old build: the reported symptom, on a released build.
-    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
-    const { __test__ } = await loadModule();
-
-    __test__.nudgeUpdateRecommended(decision, pnpmInstall());
-
-    const printed = errSpy.mock.calls.map((c) => c.join(" ")).join("\n");
-    expect(printed).toContain("5.24.0");
-    expect(printed).toContain("pnpm add -g @indigoai-us/hq-cli@latest");
-    expect(printed).not.toContain("npm install");
-  });
-
-  it("still prints the server updateCommand for an npm-managed install", async () => {
-    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
-    const { __test__ } = await loadModule();
-
-    __test__.nudgeUpdateRecommended(decision, npmInstall("/usr/local"));
-
-    const printed = errSpy.mock.calls.map((c) => c.join(" ")).join("\n");
-    expect(printed).toContain("npm install -g @indigoai-us/hq-cli@latest");
-    expect(printed).not.toContain("pnpm");
-  });
-});
-
-describe("isPnpmManagedPackageDir — global layouts only", () => {
-  it("rejects a LOCAL pnpm project dependency", async () => {
-    // `pnpm add -g` would mutate the user's GLOBAL install as a side effect of
-    // a non-global invocation, while the local copy actually running stayed
-    // stale — so the gate would re-fire (and re-install globally) forever.
-    const { __test__ } = await loadModule();
-    expect(
-      __test__.isPnpmManagedPackageDir(
-        "/Users/x/code/my-app/node_modules/.pnpm/@indigoai-us+hq-cli@5.61.0/node_modules/@indigoai-us/hq-cli",
-      ),
-    ).toBe(false);
-    expect(
-      __test__.isPnpmManagedPackageDir(
-        "/Users/x/code/my-app/node_modules/@indigoai-us/hq-cli",
-      ),
-    ).toBe(false);
-  });
-
-  it("rejects a `pnpm dlx` cache directory", async () => {
-    const { __test__ } = await loadModule();
-    expect(
-      __test__.isPnpmManagedPackageDir(
-        "/Users/x/Library/pnpm/store/v3/tmp/dlx-49281/node_modules/.pnpm/@indigoai-us+hq-cli@5.61.0/node_modules/@indigoai-us/hq-cli",
-      ),
-    ).toBe(false);
-  });
-
-  it("rejects a dlx cache even when it sits under PNPM_HOME", async () => {
-    vi.stubEnv("PNPM_HOME", "/Users/x/Library/pnpm");
-    const { __test__ } = await loadModule();
-    expect(
-      __test__.isPnpmManagedPackageDir(
-        "/Users/x/Library/pnpm/store/v3/tmp/dlx-49281/node_modules/@indigoai-us/hq-cli",
-      ),
-    ).toBe(false);
-  });
-
-  it("accepts a PNPM_HOME global root whose store dir is not numeric", async () => {
-    vi.stubEnv("PNPM_HOME", "/opt/pnpm-home");
-    const { __test__ } = await loadModule();
-    expect(
-      __test__.isPnpmManagedPackageDir(
-        "/opt/pnpm-home/global/next/node_modules/@indigoai-us/hq-cli",
-      ),
-    ).toBe(true);
-  });
-});
-
-describe("buildSpawnPlan — Windows .cmd shims", () => {
-  it("spawns through the shell on win32 (Node refuses bare .cmd since CVE-2024-27980)", async () => {
-    const { __test__ } = await loadModule();
-    const plan = __test__.buildSpawnPlan(
-      "pnpm",
-      ["add", "-g", "@indigoai-us/hq-cli@latest"],
-      "win32",
-    );
-    expect(plan.shell).toBe(true);
-    expect(plan.cmd).toBe("pnpm");
-    expect(plan.args).toEqual(["add", "-g", "@indigoai-us/hq-cli@latest"]);
-  });
-
-  it("quotes a prefix containing spaces, because Node does not quote for shell:true", async () => {
-    const { __test__ } = await loadModule();
-    const plan = __test__.buildSpawnPlan(
-      "npm",
-      ["install", "-g", "--prefix", "C:/Program Files/npm", "pkg@latest"],
-      "win32",
-    );
-    expect(plan.args).toEqual([
-      "install",
-      "-g",
-      "--prefix",
-      '"C:/Program Files/npm"',
-      "pkg@latest",
-    ]);
-  });
-
-  it("does not use a shell on posix", async () => {
-    const { __test__ } = await loadModule();
-    const plan = __test__.buildSpawnPlan("pnpm", ["add", "-g", "x"], "darwin");
-    expect(plan).toEqual({ cmd: "pnpm", args: ["add", "-g", "x"], shell: false });
-  });
-});
-
-describe("pnpm-managed installs — pnpm not spawnable", () => {
-  it("exits 75 with an actionable message when pnpm is missing from PATH", async () => {
-    // launchd/cron and other minimal-PATH parents never source the profile that
-    // puts PNPM_HOME on PATH. spawnSync surfaces that as an ENOENT `error`, not
-    // a throw and not a non-zero status.
-    const errSpy = 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().mockReturnValue({
-      ok: false,
-      code: "ENOENT",
-      detail: "spawnSync pnpm ENOENT",
-    });
-    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",
-        },
-        { resolveInstall: () => pnpmInstall(), runner },
-      ),
-    ).toThrow(/__process_exit__:75/);
-
-    expect(exitSpy).toHaveBeenCalledWith(75);
-    const printed = errSpy.mock.calls.map((c) => c.join(" ")).join("\n");
-    expect(printed).toContain("not found on PATH");
-    expect(printed).toContain("Try manually: pnpm add -g @indigoai-us/hq-cli@latest");
-    // The server's npm command may be shown, but only flagged as npm-only —
-    // never as the thing to run for this layout.
-    expect(printed).not.toMatch(/Try manually: npm/);
-    // Still no sudo retry: it would install into root's PNPM_HOME.
-    expect(runner).not.toHaveBeenCalledWith("sudo", expect.anything());
-  });
-});
-
-describe("resolveRunningInstall", () => {
-  it("is consulted exactly once per enforceUpdateRequired invocation", async () => {
-    // Manager and prefix used to be resolved by two independent walks of the
-    // directory tree, each reading and JSON-parsing a package.json per level,
-    // and the two could disagree if the filesystem moved between them.
-    vi.spyOn(console, "error").mockImplementation(() => {});
-    vi.spyOn(process, "exit").mockImplementation(((code?: number) => {
-      throw new Error(`__process_exit__:${code ?? 0}`);
-    }) as never);
-    const resolveInstall = vi.fn(() => npmInstall("/usr/local"));
-    const runner = vi.fn().mockReturnValue({ ok: true });
-    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",
-        },
-        { resolveInstall, runner },
-      ),
-    ).toThrow(/__process_exit__:0/);
-
-    expect(resolveInstall).toHaveBeenCalledTimes(1);
-  });
-
-  it("reports manager and prefix from a single resolution", async () => {
-    const { __test__ } = await loadModule();
-    const install = __test__.resolveRunningInstall();
-    expect(install.manager).toBe(__test__.resolveRunningManager());
-    expect(install.prefix).toBe(__test__.resolveRunningPrefix());
-    // A pnpm-managed install must never carry an npm prefix.
-    if (install.manager === "pnpm") expect(install.prefix).toBeNull();
-  });
-});