@indigoai-us/hq-cli 5.50.0 → 5.50.2

package/src/utils/pack-contributions.ts

@@ -1,26 +1,97 @@
 /**
- * Content-pack contribution helpers -- the single source of truth (in TS) for
- * the `contributes.* -> host-path` symlink mapping that `hq install` wires via
+ * Content-pack contribution helpers -- the SINGLE SOURCE OF TRUTH (US-003) for
+ * the `contributes.* -> host` mapping that `hq install` wires via
  * `core/scripts/scan-packages.sh`.
  *
  * `pack-install.ts` only INSTALLS content packs (into `core/packages/<name>/`,
  * tracked by filesystem presence -- there is no registry file). The list /
  * update / uninstall lifecycle in `commands/packs.ts` needs to reason about the
  * SAME mapping so it can report link health and cleanly un-wire a pack without
- * leaving dangling symlinks. That mapping is duplicated today in two places:
+ * leaving dangling symlinks.
  *
- *   - core/scripts/scan-packages.sh  (bash `case`, the wiring authority)
- *   - pack-install.ts validateManifest's `subpaths` record (payload validation)
+ * Historically that mapping was RESTATED in five places (the scan-packages.sh
+ * bash `case`, pack-install.ts:validateManifest's `subpaths` record,
+ * `linkFor`'s switch, `contributionLinks`, and the `PackContributeKey` union),
+ * drift-guarded only by a substring check. US-003 collapses it to ONE
+ * declarative table -- `CONTRIBUTION_TABLE` below -- with a row per key
+ * `{ payload, host, wire }`:
  *
- * This module re-encodes it once for TS callers. A parity test
- * (`pack-contributions.test.ts`) asserts it matches scan-packages.sh's `case`
- * arms so the three copies cannot drift.
+ *   - `PackContributeKey` is DERIVED from the table keys (see types.ts).
+ *   - `linkFor` / `contributionLinks` / the `subpaths` validator READ the table.
+ *   - `core/scripts/scan-packages.sh` reads a generated data block emitted from
+ *     this same table (regenerate via `scripts/generate-scan-packages-table.mjs`).
+ *
+ * A parity test (`pack-contributions.test.ts`) asserts FULL key-set +
+ * payload-suffix + wire-mode equivalence across every surface, so the copies
+ * cannot drift.
+ *
+ * `wire` discriminates HOW a contribution reaches the host:
+ *   - `symlink`: a single `ln -s` into a well-known host directory (every
+ *     contribution type that shipped before MCP).
+ *   - `merge`: the contribution is MERGED into a shared host config rather than
+ *     symlinked (the `mcp` row -- registered into the Claude + Codex agent
+ *     configs). The merge WIRING is delivered in US-004/US-005; US-003 only
+ *     DECLARES the row as data so the table is the single source and the parity
+ *     test guards the real invariant. `symlink`-only readers (linkFor,
+ *     contributionLinks, the symlink validator, scan-packages) must SKIP
+ *     `merge` rows -- they never produce a symlink.
  */
 
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
 import type { PackManifest, PackContributeKey } from '../types.js';
+import { CONTRIBUTION_TABLE, payloadFor, type WireMode } from './contribution-table.js';
+import {
+  unregisterMcpServers,
+  type UnregisterServerResult,
+  type SafeWriteEnv,
+  type AcquireLockOptions,
+} from '../commands/mcp-registration.js';
+
+// NOTE on dependency direction: this module imports from ../commands/mcp-registration.js
+// to un-register `wire:merge` (mcp) servers on uninstall. mcp-registration.ts imports
+// ONLY fs/os/path/smol-toml (it does NOT import from pack-contributions.ts), so there
+// is NO import cycle. If that ever changes, invert via a callback injected by packs.ts.
+
+export { CONTRIBUTION_TABLE };
+export type { WireMode };
+
+/**
+ * Where a contributes key is ROUTED (US-005). Reads the single-source table's
+ * `wire` field — `'symlink'` keys go through `linkFor`/`contributionLinks` (a
+ * host `ln -s`); `'merge'` keys (e.g. `mcp`) go through the `registerMcpServers`
+ * seam in `commands/mcp-registration.ts` and are NEVER symlinked.
+ *
+ * This is the explicit, code-enforced discriminator behind the invariant that
+ * merge keys never reach the symlink path: callers fan out on the return value
+ * rather than relying on `linkFor` happening to return `null`.
+ */
+export function routeContribution(key: PackContributeKey): WireMode {
+  return CONTRIBUTION_TABLE[key].wire;
+}
+
+/**
+ * The subset of a pack's declared `contributes` keys that are `wire: 'merge'`
+ * (e.g. `mcp`) — the keys that MUST be routed to `registerMcpServers` (US-006)
+ * and MUST NOT be symlinked. Unknown keys and non-array/empty values are
+ * ignored, mirroring `contributionLinks`. Returned in `contributes` iteration
+ * order, de-duplicated.
+ */
+export function mergeKeys(
+  contributes: Partial<Record<PackContributeKey, string[]>>,
+): PackContributeKey[] {
+  const out: PackContributeKey[] = [];
+  for (const [key, items] of Object.entries(contributes) as [
+    PackContributeKey,
+    unknown,
+  ][]) {
+    if (!(key in CONTRIBUTION_TABLE)) continue; // unknown key -> ignore
+    if (!Array.isArray(items) || items.length === 0) continue;
+    if (routeContribution(key) === 'merge' && !out.includes(key)) out.push(key);
+  }
+  return out;
+}
 
 /** A single symlink a pack contributes: dst (host path) -> src (inside pack). */
 export interface WiredLink {
@@ -37,58 +108,40 @@ export type LinkStatus =
   | 'foreign'; // dst exists but points elsewhere or is a real file (collision)
 
 /**
- * Map one contributes entry to its source/host paths. MUST stay in lockstep
- * with scan-packages.sh:wire_one_package and pack-install.ts:validateManifest.
+ * Map one SYMLINK contributes entry to its source/host paths, READING the
+ * single-source `CONTRIBUTION_TABLE` (US-003). The src is the expanded pack
+ * payload; the dst is `<host-dir>/<payload-basename>` so per-key suffixes
+ * (`.md`, `.sh`, none) carry through.
+ *
+ * Returns `null` for a `wire: 'merge'` key (e.g. `mcp`): a merge contribution
+ * is not a symlink and has no `WiredLink`. Callers that only handle symlinks
+ * (contributionLinks/unwirePack) skip those keys.
  */
 function linkFor(
   hqRoot: string,
   packDir: string,
   key: PackContributeKey,
   item: string,
-): WiredLink {
-  let srcRel: string;
-  let dstRel: string;
-  switch (key) {
-    case 'workers':
-      srcRel = path.join('workers', item);
-      dstRel = path.join('core', 'workers', 'public', item);
-      break;
-    case 'knowledge':
-      srcRel = path.join('knowledge', item);
-      dstRel = path.join('core', 'knowledge', 'public', item);
-      break;
-    case 'skills':
-      srcRel = path.join('skills', item);
-      dstRel = path.join('.claude', 'skills', item);
-      break;
-    case 'commands':
-      srcRel = path.join('commands', `${item}.md`);
-      dstRel = path.join('.claude', 'commands', `${item}.md`);
-      break;
-    case 'hooks':
-      srcRel = path.join('hooks', `${item}.sh`);
-      dstRel = path.join('.claude', 'hooks', `${item}.sh`);
-      break;
-    case 'policies':
-      srcRel = path.join('policies', `${item}.md`);
-      dstRel = path.join('core', 'policies', `${item}.md`);
-      break;
-    case 'scripts':
-      srcRel = path.join('scripts', item);
-      dstRel = path.join('core', 'scripts', item);
-      break;
-  }
+): WiredLink | null {
+  const row = CONTRIBUTION_TABLE[key];
+  if (row.wire !== 'symlink') return null;
+  const payloadRel = payloadFor(key, item); // e.g. commands/foo.md
+  // dst keeps the payload's basename (so the suffix carries through) under the
+  // host directory declared in the table.
+  const dstRel = path.join(row.host, path.basename(payloadRel));
   return {
     key,
     item,
-    src: path.join(packDir, srcRel),
+    src: path.join(packDir, payloadRel),
     dst: path.join(hqRoot, dstRel),
   };
 }
 
 /**
- * Every symlink a pack's `contributes` block declares. Empty subfields and
- * non-array values are ignored, mirroring scan-packages.sh.
+ * Every SYMLINK a pack's `contributes` block declares. Empty subfields and
+ * non-array values are ignored, mirroring scan-packages.sh. `wire: 'merge'`
+ * keys (e.g. `mcp`) produce no symlink and are skipped here -- their host
+ * effect (a config merge) is handled separately (US-004/US-005).
  */
 export function contributionLinks(
   hqRoot: string,
@@ -100,10 +153,17 @@ export function contributionLinks(
     PackContributeKey,
     unknown,
   ][]) {
+    if (!(key in CONTRIBUTION_TABLE)) continue; // unknown key -> ignore
     if (!Array.isArray(items)) continue;
+    // INVARIANT (US-005): merge keys are NEVER symlinked. They route to
+    // registerMcpServers (commands/mcp-registration.ts) instead. Skip them
+    // explicitly here -- not just via linkFor returning null -- so the symlink
+    // path provably excludes them.
+    if (routeContribution(key) === 'merge') continue;
     for (const item of items) {
       if (typeof item !== 'string' || item.length === 0) continue;
-      links.push(linkFor(hqRoot, packDir, key, item));
+      const link = linkFor(hqRoot, packDir, key, item);
+      if (link) links.push(link); // null for merge keys -- skip
     }
   }
   return links;
@@ -204,6 +264,23 @@ export function listInstalledPacks(hqRoot: string): InstalledPack[] {
   return out;
 }
 
+/**
+ * Installed packs that declare `name` in their `requires.packs` (M0). Pure over
+ * the supplied list — the uninstall dependents guard calls this with
+ * `listInstalledPacks(hqRoot)`. Excludes the pack named `name` itself, so a
+ * self-reference never counts as its own dependent.
+ */
+export function findDependentPacks(
+  installed: InstalledPack[],
+  name: string,
+): InstalledPack[] {
+  return installed.filter(
+    (p) =>
+      p.name !== name &&
+      (p.manifest?.requires?.packs ?? []).some((d) => d.name === name),
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Un-wiring (the uninstall guarantee)
 // ---------------------------------------------------------------------------
@@ -256,6 +333,76 @@ export function unwirePack(
   return result;
 }
 
+// ---------------------------------------------------------------------------
+// MCP un-wiring (US-009) — the `wire: 'merge'` parallel to symlink un-wiring.
+//
+// `unwirePack` above only removes SYMLINKS: it iterates `contributionLinks`, which
+// SKIPS every `wire: 'merge'` key (e.g. `mcp`). So a pack's MCP servers — registered
+// into ~/.claude.json + ~/.codex/config.toml, NOT symlinked — are INVISIBLE to the
+// symlink unwire and would leak after uninstall. `unwirePackMcp` is the parallel
+// path: for each name in `contributes.mcp` it calls `unregisterMcpServers` (US-009),
+// which removes ONLY entries whose `_hqPack` provenance matches THIS pack and
+// skip-and-warns on any foreign/unstamped same-named entry.
+//
+// Kept as a SEPARATE, composable call from `unwirePack` (not folded into it) so the
+// existing `unwirePack` signature + tests stay intact and each path is testable in
+// isolation. The uninstall command composes both (symlink unwire + MCP unwire).
+// ---------------------------------------------------------------------------
+
+/** The result of {@link unwirePackMcp}: the per-server un-registration outcomes (empty when no `mcp` keys). */
+export interface UnwireMcpResult {
+  /** One {@link UnregisterServerResult} per declared `contributes.mcp` server, in declaration order. */
+  servers: UnregisterServerResult[];
+}
+
+/** Tuning passthrough for {@link unwirePackMcp} (tests inject a tmpdir `env.home` + tiny lock timeouts). */
+export interface UnwirePackMcpOptions {
+  /** Injectable env — tests MUST pass a tmpdir `home` so the real ~/.claude.json / ~/.codex are untouched. */
+  env?: Partial<SafeWriteEnv>;
+  /** Lock tuning (tests use tiny timeouts). */
+  lock?: AcquireLockOptions;
+  /** Backup timestamp override (deterministic tests). */
+  stamp?: string;
+}
+
+/**
+ * Un-register the `wire: 'merge'` (MCP) servers a pack declares — the parallel to
+ * {@link unwirePack}'s symlink removal. For each name in `mergeKeys(contributes)` →
+ * `contributes.<mergeKey>` (today only `mcp`), this delegates to
+ * {@link unregisterMcpServers}, which removes ONLY entries stamped with THIS pack's
+ * `_hqPack` provenance and SKIPS-AND-WARNS on a foreign/unstamped same-named entry.
+ *
+ * No-ops cleanly when the pack declares no merge keys (returns `{ servers: [] }`),
+ * when the runtime config is absent (Codex-less host → first-class skip; missing
+ * ~/.claude.json → `absent`), and on a re-run (already-removed → `absent`). It does
+ * NOT throw on a foreign entry — uninstall of one pack must not abort on a server
+ * another pack (or the user) owns.
+ *
+ * @param packName    the pack being uninstalled — the provenance to match
+ * @param contributes the pack's `contributes` block (its `mcp` list drives removal)
+ */
+export function unwirePackMcp(
+  packName: string,
+  contributes: Partial<Record<PackContributeKey, string[]>>,
+  options?: UnwirePackMcpOptions,
+): UnwireMcpResult {
+  const servers: UnregisterServerResult[] = [];
+  for (const key of mergeKeys(contributes)) {
+    const names = (contributes[key] ?? []).filter(
+      (n): n is string => typeof n === 'string' && n.length > 0,
+    );
+    if (names.length === 0) continue;
+    servers.push(
+      ...unregisterMcpServers(packName, names, {
+        env: options?.env,
+        lock: options?.lock,
+        stamp: options?.stamp,
+      }),
+    );
+  }
+  return { servers };
+}
+
 // ---------------------------------------------------------------------------
 // Host introspection: hqVersion + recommended_packages catalog
 // ---------------------------------------------------------------------------

package/src/utils/secrets-cache.ts

@@ -142,6 +142,28 @@ export function writeCache(
   }
 }
 
+/**
+ * List the scope UIDs (`cmp_*` / `prs_*` subdirectories) that currently have a
+ * secrets-cache directory on disk. Used by offline callers (e.g. install-time MCP
+ * registration) that have no `--company` flag and no network token and so cannot
+ * resolve a single active company UID up front: they instead probe every cached
+ * scope for a given secret name. Returns `[]` when the cache root is absent or
+ * unreadable (the desired graceful-deferral behavior — no scopes, no hits).
+ */
+export function listSecretCacheScopes(): string[] {
+  try {
+    return fs
+      .readdirSync(CACHE_DIR, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+      // Only real entity scopes (cmp_*/prs_*); validateInputs in readCache also
+      // rejects anything with `/` or `..`, so this is belt-and-suspenders.
+      .filter((name) => !name.startsWith("."));
+  } catch {
+    return [];
+  }
+}
+
 export function removeCacheEntry(companyUid: string, name: string): void {
   if (!validateInputs(companyUid, name)) return;
   const filePath = path.join(CACHE_DIR, companyUid, name);

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

@@ -49,6 +49,51 @@ describe("shouldSkipGate", () => {
   });
 });
 
+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");
@@ -242,4 +287,81 @@ describe("enforceVersionGate — hard-update path", () => {
     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",
+        },
+        {
+          resolvePrefix: () => 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,
+          resolvePrefix: () => null,
+        },
+      ),
+    ).toThrow(/__process_exit__:0/);
+
+    expect(exitSpy).toHaveBeenCalledWith(0);
+    expect(performUpdateString).toHaveBeenCalledWith(updateCommand);
+  });
 });

package/src/utils/version-gate.ts

@@ -29,13 +29,17 @@
  */
 
 import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import chalk from "chalk";
-import { CLI_VERSION } from "../cli-version.js";
+import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
 import { DEFAULT_VAULT_API_URL } from "./cognito-session.js";
 
 const CLIENT_ID = "hq-cli";
 const ENDPOINT_PATH = "/v1/client-version/check";
 const FETCH_TIMEOUT_MS = 3_000;
+const LATEST_PACKAGE_SPEC = `${CLI_NAME}@latest`;
 
 interface VersionCheckResponse {
   clientId: string;
@@ -53,6 +57,53 @@ function isOptedOut(): boolean {
   return process.env.HQ_NO_UPDATE_CHECK === "1";
 }
 
+function findRunningPackageRoot(): string | null {
+  let dir = path.dirname(fileURLToPath(import.meta.url));
+  while (true) {
+    try {
+      const pkg = JSON.parse(
+        readFileSync(path.join(dir, "package.json"), "utf-8"),
+      ) as { name?: unknown };
+      if (pkg.name === CLI_NAME) return dir;
+    } catch {
+      // Keep walking; compiled installs usually start under dist/.
+    }
+
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export function npmPrefixFromPackageDir(pkgDir: string): string | null {
+  const normalized = pkgDir.replace(/\\/g, "/").replace(/\/+$/, "");
+  const segments = normalized.split("/");
+  const nodeModulesIndex = segments.lastIndexOf("node_modules");
+  if (nodeModulesIndex === -1) return null;
+
+  const prefixEnd =
+    segments[nodeModulesIndex - 1] === "lib"
+      ? nodeModulesIndex - 1
+      : nodeModulesIndex;
+  const prefix = segments.slice(0, prefixEnd).join("/");
+  if (prefix === "" && normalized.startsWith("/")) return "/";
+  return prefix || null;
+}
+
+export function resolveRunningPrefix(): string | null {
+  try {
+    const pkgRoot = findRunningPackageRoot();
+    if (!pkgRoot) return null;
+    return npmPrefixFromPackageDir(pkgRoot);
+  } catch {
+    return null;
+  }
+}
+
+export function buildPrefixedInstallArgv(prefix: string): string[] {
+  return ["install", "-g", "--prefix", prefix, LATEST_PACKAGE_SPEC];
+}
+
 /**
  * Hit POST /v1/client-version/check. Returns the parsed body on 200, or
  * `null` on any failure (caller treats as "no gate"). Tight 3s timeout —
@@ -95,13 +146,10 @@ async function fetchVersionDecision(): Promise<VersionCheckResponse | null> {
  * forcing a re-invocation would run twice on the same process and feel
  * janky; instead we print a clear "rerun your command" message and exit.
  */
-function performUpdate(
-  command: string,
-): { ok: boolean; detail?: string } {
-  const parts = command.split(/\s+/).filter(Boolean);
-  if (parts.length === 0) return { ok: false, detail: "empty command" };
-  const cmd = parts[0]!;
-  const args = parts.slice(1);
+type UpdateResult = { ok: boolean; detail?: string };
+type UpdateRunner = (cmd: string, args: string[]) => UpdateResult;
+
+function runUpdateCommand(cmd: string, args: string[]): UpdateResult {
   try {
     const result = spawnSync(cmd, args, { stdio: "inherit" });
     if (result.status !== 0) {
@@ -116,6 +164,25 @@ function performUpdate(
   }
 }
 
+function performUpdateCommand(
+  cmd: string,
+  args: string[],
+  runner: UpdateRunner = runUpdateCommand,
+): UpdateResult {
+  return runner(cmd, args);
+}
+
+function performUpdate(
+  command: string,
+  runner: UpdateRunner = runUpdateCommand,
+): UpdateResult {
+  const parts = command.split(/\s+/).filter(Boolean);
+  if (parts.length === 0) return { ok: false, detail: "empty command" };
+  const cmd = parts[0]!;
+  const args = parts.slice(1);
+  return performUpdateCommand(cmd, args, runner);
+}
+
 /**
  * Soft notify when the server says we're below `latestVersion` but still ≥
  * `minVersion`. Single chalk-yellow line on stderr; never blocks.
@@ -140,7 +207,14 @@ function nudgeUpdateRecommended(decision: VersionCheckResponse): void {
  *   0 — update succeeded; user must rerun their command
  *   75 — update failed (EX_TEMPFAIL; common for sudo/EACCES on system npm)
  */
-function enforceUpdateRequired(decision: VersionCheckResponse): never {
+function enforceUpdateRequired(
+  decision: VersionCheckResponse,
+  deps: {
+    performUpdateString?: (command: string) => UpdateResult;
+    resolvePrefix?: () => string | null;
+    runner?: UpdateRunner;
+  } = {},
+): never {
   const banner = chalk.red.bold(
     `✗ hq-cli ${decision.currentVersion} is below the minimum required version (${decision.minVersion}).`,
   );
@@ -148,7 +222,8 @@ function enforceUpdateRequired(decision: VersionCheckResponse): never {
   if (decision.message) console.error(chalk.dim(`  ${decision.message}`));
 
   const command = decision.updateCommand;
-  if (!command) {
+  const prefix = (deps.resolvePrefix ?? resolveRunningPrefix)();
+  if (!command && !prefix) {
     console.error(
       chalk.red(
         "  No updateCommand provided by hq-pro — see https://hq.indigo.ai/docs/cli-update for manual steps.",
@@ -160,13 +235,28 @@ function enforceUpdateRequired(decision: VersionCheckResponse): never {
     process.exit(75);
   }
 
-  console.error(chalk.dim(`  Running: ${command}`));
-  const result = performUpdate(command);
+  const runner = deps.runner ?? runUpdateCommand;
+  const result = prefix
+    ? (() => {
+        const args = buildPrefixedInstallArgv(prefix);
+        console.error(chalk.dim(`  Installing into npm prefix: ${prefix}`));
+        console.error(chalk.dim(`  Running: npm ${args.join(" ")}`));
+        return performUpdateCommand("npm", args, runner);
+      })()
+    : (() => {
+        console.error(chalk.dim(`  Running: ${command}`));
+        return deps.performUpdateString
+          ? deps.performUpdateString(command!)
+          : performUpdate(command!, runner);
+      })();
   if (!result.ok) {
     console.error(
       chalk.red(`✗ Update failed${result.detail ? `: ${result.detail}` : ""}.`),
     );
-    console.error(chalk.dim(`  Try manually: ${command}`));
+    const manual = prefix
+      ? `npm ${buildPrefixedInstallArgv(prefix).join(" ")}`
+      : command!;
+    console.error(chalk.dim(`  Try manually: ${manual}`));
     process.exit(75);
   }
 
@@ -215,5 +305,11 @@ export const __test__ = {
   CLIENT_ID,
   ENDPOINT_PATH,
   FETCH_TIMEOUT_MS,
+  buildPrefixedInstallArgv,
+  enforceUpdateRequired,
+  npmPrefixFromPackageDir,
   performUpdate,
+  performUpdateCommand,
+  runUpdateCommand,
+  resolveRunningPrefix,
 };